Webhooks

Voice API webhooks provide real-time notifications about events occurring during call processing. These webhooks enable your application to respond to various telephony events with custom business logic.

Webhooks can be configured in three different ways:

1. Connection Webhook Config: Default webhook configuration tied to a connection.
2. Custom Webhook Config: Webhook settings specified per command.
3. Events Webhook Config: Advanced configuration allowing different URLs for different event types.

The connection level configuration contains the following configuration parameters:

• webhook_url: Primary destination for webhook delivery
• webhook_url_method: HTTP method for webhook requests (default: "POST")
• failover_url: Secondary destination if primary fails
• webhook_api_version: API version for webhook format ("1" or "2")
• webhook_timeout_seconds: Timeout for webhook requests

• Webhooks are sent using either POST or GET methods as specified in the webhook_url_method parameter.
• By default, all webhooks are sent using the POST method if not otherwise specified.
• For POST requests, the webhook payload is sent in the request body as JSON.
• For GET requests, the webhook payload is encoded in the URL query parameters.

Webhook requests include the following headers:

• Content-Type: application/json (for POST requests)
• User-Agent: telnyx-webhooks
• Telnyx-Signature-Ed25519: Webhook signature for verification
• Telnyx-Timestamp: Unix timestamp when the webhook was generated

Webhook requests contain the following parameters:

All webhook events include these common parameters:

Parameter	Type	Description
id	String	Unique identifier for the webhook event
record_type	String	Always "event" for webhooks
event_type	String	Type of event (see event types tables)
occurred_at	String	ISO-8601 timestamp when the event was created
payload	Object	Contains event-specific data

The payload object contains parameters specific to each event type, but common fields include:

Parameter	Type	Description
call_control_id	String	Unique identifier for the call control session
call_leg_id	String	Unique identifier for the specific call leg
call_session_id	String	Unique identifier for the entire call session
connection_id	String	Identifier for the connection used
from	String	Calling party phone number or address
to	String	Called party phone number or address

For security, all webhooks are signed using ED25519. For more information, see the webhook signing documentation.

All expected webhooks are specified in the documentation for each of the Voice REST endpoint i.e. Make a new call endpoint.

1. When an event occurs, the system checks if webhooks are enabled for the connection
2. The system determines which webhook configuration to use (connection, custom, or event-specific)
3. The webhook payload is constructed with event data
4. The system attempts to deliver the webhook to the configured URL
5. If delivery fails and a failover URL is configured, the system attempts delivery to the failover URL
6. The system logs the webhook delivery attempt

The following HTTP response codes determine if a webhook delivery is successful:

• 2xx: Success, webhook received
• 3xx: Redirect (system will follow up to 3 redirects)
• 4xx: Client error (no retry, except for 408 Request Timeout and 429 Too Many Requests)
• 5xx: Server error (will trigger retry mechanism)

1. Implement idempotency: Webhooks may be delivered more than once in rare cases
2. Respond quickly: Return 2xx HTTP responses promptly (within 10 seconds) to acknowledge receipt
3. Use webhooks for event notifications only: Do not rely on webhooks for critical control flow
4. Implement signature verification: Always validate webhook authenticity using the provided signature
5. Handle webhook timeouts: Configure reasonable timeout values
6. Monitor webhook deliveries: Track failed webhooks and implement alerting for critical events
7. Create a webhook testing environment: Test your webhook handlers before deploying to production
8. Implement graceful degradation: Have fallback mechanisms if webhooks are delayed or missing