Webhook
⚡ 5 min readConfigure 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
2xxstatus 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