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
Slack	Supported
Discord	Supported
Microsoft Teams	Coming soon
KakaoWork	Coming soon
Telegram	Coming soon

Only active channels receive messages. Configure Slack and Discord in Console today.

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 (verified retry allow, session-create failure).

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 (MFA pending)	Not logged	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 (permission 0)	Not logged	None
Step-up session create failed (`deny-stepup-failure`)	medium `guard_gate_decision`	None
No MAT in CLI	Not logged	None
Ungated / RBAC allow without step-up	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