Webhook

⚡ 5 min read

Configure webhooks to receive real-time notifications for authentication events

What Webhooks Do

Webhooks deliver real-time HTTP POST notifications to your server when authentication events occur in your Transcodes project. Instead of polling for changes, your backend receives events as they happen.

Common use cases:

Send Slack notifications on new user registrations
Sync user data to your database on login events
Trigger workflows on MFA completions
Maintain audit trails in external systems

Supported Event Types

Transcodes fires webhooks for the following event categories:

Category	Events	Description
Login	`login.success`, `login.failure`	User authentication attempts
Registration	`registration.success`	New user sign-ups
MFA	`mfa.success`, `mfa.failure`	Step-up authentication events
Audit	`audit.action`	Custom tracked user actions

You can subscribe to specific event types or receive all events. Filter by event type in your webhook handler

Configuring Webhooks

Open the Webhook Panel

Log in to Transcodes Console
Open your project
Locate the Authentication Kit Cluster
Click the Webhook card

Set Your Endpoint URL

Enter the HTTPS URL where you want to receive webhook events. Your endpoint must:

Accept HTTP POST requests
Return a 2xx status code to acknowledge receipt
Respond within 10 seconds

Select Event Types

Choose which events should trigger webhook notifications. You can select individual events or subscribe to all events.

Save Configuration

Click Save to activate the webhook. Transcodes will send a test ping to verify your endpoint is reachable.

Webhook endpoints must use HTTPS. Plain HTTP endpoints are not supported for security reasons

Payload Format

Webhook payloads are sent as JSON in the HTTP POST body:


{
  "id": "evt_a1b2c3d4e5f6",
  "type": "login.success",
  "timestamp": "2025-12-16T20:21:34Z",
  "projectId": "proj_abc123",
  "data": {
    "userId": "usr_xyz789",
    "email": "user@example.com",
    "method": "passkey",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0..."
  }
}

Payload fields:

Field	Type	Description
`id`	`string`	Unique event identifier
`type`	`string`	Event type (e.g., `login.success`)
`timestamp`	`string`	ISO 8601 timestamp
`projectId`	`string`	Project that generated the event
`data`	`object`	Event-specific data

Slack Integration

Transcodes supports sending webhook notifications directly to Slack channels.

Create a Slack Incoming Webhook

Go to your Slack App settings
Create a new app or select an existing one
Enable Incoming Webhooks
Add a new webhook to your desired channel
Copy the webhook URL

Configure in Transcodes

Open the Webhook panel in Transcodes Console
Paste the Slack webhook URL as your endpoint
Select the events you want to receive in Slack
Save the configuration

Slack messages will include a formatted summary of each event with user details and timestamps.

Testing Webhooks

From the Console:

Open the Webhook panel
Click Send Test Event
Verify your endpoint receives the test payload

Using a testing tool:

You can use services like webhook.site or ngrok during development to inspect incoming webhook payloads before connecting your production endpoint.

Error Handling and Retries

If your endpoint fails to respond with a 2xx status code, Transcodes implements an automatic retry strategy:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed retries, the event is marked as failed. You can view failed deliveries in the webhook panel and manually retry them.

Design your webhook handler to be idempotent. The same event may be delivered more than once due to retries or network issues. Use the id field to deduplicate events

What to do next?

After setting up webhooks:

Track user activity with Audit Logs
Configure API token (x-transcodes-token) for server-to-server Transcodes API calls
Review Events API for programmatic event access