Webhook

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

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:

• SDK redirectToStepUp when RBAC returns stepup
• Other hosted-auth session creates that share the same backend (signin, console redirects)
• AI Agent (MCP) step-up — Coming Soon

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

This alert is not tied to an AI Agent gate audit row. SDK step-up can send a session webhook without a guard audit.

AI Agent (MCP) webhooks — Coming Soon

Automatic webhooks for transcodes-guard step-up and MCP get_security_logs queries are Coming Soon. Installation is not available yet.

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.

Related