Webhook

⚡ 4 min read

Outbound notifications to chat when important auth or audit events occur. Configure incoming webhook URLs in Transcodes Console — this is not a generic event subscription API.

Supported channels

Console: Authentication Kit Cluster → Webhook

Channel	Console UI	Delivery
Slack	Configure + test	Supported
Discord	Configure + test	Supported
Microsoft Teams	Not in Console yet	Backend-ready
KakaoWork	Not in Console yet	Backend-ready
Telegram	Not in Console yet	Backend-ready (URL + chat id)

Only channels marked active receive messages. Today you configure Slack and Discord in Console; other channel types can be stored on the project but are not exposed in the Console panel yet.

When notifications fire

Transcodes uses two independent paths. Both are best-effort (5 s timeout per channel). Failed sends never block audit writes or session creation.

1. Audit log webhooks

Fires when a row is written to Audit Logs and either:

severity is high (includes successful and failed step-up MFA on Transcodes Auth), or
the client set webhookNotification: true (any severity — SDK trackUserAction second argument).

Message shape: [Audit] {tag}, status, severity, actor, role, timestamp, optional metadata.

Does not fire for guard_gate_decision rows at medium or low severity (hook block, RBAC deny, verified retry allow).

2. Browser session webhooks

Fires when Transcodes Cloud creates a pending hosted-auth session and returns a verify URL — before MFA completes.

Covers:

transcodes-guard step-up (MCP / risky shell)
SDK redirectToStepUp when RBAC returns stepup
Other hosted-auth session creates that share the same backend (signin, console redirects)

Message shape: [Step-up] Re-authentication requested, actor, optional resource/action/reason, Verify: URL, expiry.

This alert is not tied to the guard_gate_decision audit row. You can receive a session webhook even when no gate audit was written (for example SDK step-up without transcodes-guard).

transcodes-guard step-up: audit vs webhook

transcodes-guard writes audit rows to the same log as your app. Webhooks follow the rules above — not every audit row sends chat.

When step-up is required (MAT configured)

Stage	Audit log	Chat webhook
Hook blocks command; backend creates session	`guard_gate_decision` · medium · `decision: deny-stepup-pending`	Session webhook (verify URL)
Human completes MFA on Transcodes Auth	`{resource}:{action}` or `mcp:stepup` · high · `status: true`	Audit webhook
Human fails MFA (wrong code, verify error, etc.)	same tag · high · `status: false`	Audit webhook
Same command retries after verified session	`guard_gate_decision` · low · `decision: allow`	None

Raw shell text is never included in audit metadata — only resource, action, rule id, and command fingerprint (fp).

Other hook outcomes

Outcome	Audit log	Chat webhook
RBAC deny (`deny-rbac-denied`)	medium `guard_gate_decision`	None
Step-up session create failed (`deny-stepup-failure`)	medium `guard_gate_decision`	None
No MAT in CLI (`deny-no-token`)	Not logged	None
Safe command (`pass`)	Not logged	None

Full tag reference and token attribution: Audit Logs.

Query in Console Audit Logs or MCP get_security_logs — filter tag=guard_gate_decision or tag=mcp:stepup.

Test a channel

Console Webhook panel → Send test message (Slack or Discord).

The test uses the audit message format ([Audit] webhook:test, high severity) so you can confirm URL and activation before production traffic.

SDK tip

Force an audit webhook on a non-high event:


await transcodes.trackUserAction(
  { tag: 'billing:refund', severity: 'medium', status: true },
  { webhookNotification: true },
);

Step-up from your web app: when redirectToStepUp opens Transcodes Auth, the session webhook fires from session creation; after MFA, the high-severity audit row triggers the audit webhook (same as MCP step-up).

Audit Logs AI Agent (MCP)Step-up Auth