Webhook destination

(new)

Beta

Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.

The Webhook destination delivers your events as HTTP requests directly to an endpoint you control. You can receive and process raw event data in your own systems without a native connector.

Destination overview

Category: Raw data
Release status: Beta
Authentication: None
Regional availability: US1, IE1

Join the Data Destinations private beta

Get early access to native destinations for data warehouses, observability tools, and event pipelines.

Eligible events

Webhook has no restriction: all Event Types are eligible for delivery.

In the IE1 region, only Voice Insights events are eligible for delivery at this time.

Get started

Prerequisites

Before you set up a Webhook destination, make sure you have:

An HTTP(S) endpoint that is publicly reachable and responds within 2 seconds.
The endpoint configured to accept POST requests with a JSON body.
Optional: credentials embedded in the webhook URL (https://user:pass@host/path), if your endpoint requires authentication. Twilio extracts them automatically and sends them as an Authorization header instead of forwarding the URL as is.

Create the destination

(information)

Info

See Set up a destination for the full UI and Destinations API setup flow common to every destination type.

Twilio Console

To create a Webhook destination in the Twilio Console:

Gather the settings listed in Destination settings.
In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
Complete the Add destination subscription wizard.

Destinations API

To create a Webhook destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to webhook. For authentication and the other request body fields, see Create a destination.

Create a destination

POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"

Set the config object in the request body as follows:

Name	Type	Description
`method`	enum`<string>`	The HTTP method Twilio uses to deliver events. The only supported value is `POST`.
`url` (Required)	string	The URL of your publicly accessible HTTP endpoint.

The following example shows a request body. Replace the example URL with your endpoint.

Example request body

1{
2  "destinationType": "webhook",
3  "name": "My Webhook destination",
4  "config": {
5    "url": "https://example.com/webhooks/twilio"
6  }
7}

Destination settings

Use webhook as the destinationType.

Field	Description	Required	Options
Webhook URL	The endpoint Twilio delivers events to. Supports embedded HTTP basic-auth credentials (`https://user:pass@host/path`). Cannot be changed after the destination is created.	Yes	User Defined
HTTP Method	The HTTP method Twilio uses to send requests to your endpoint. You can't change this after you create the destination. New subscriptions must use `POST`. `GET` is being phased out and supported only for subscriptions created before October 1, 2026.	No	Post

You can't change either field after you create the destination. To change the URL or HTTP Method, create a new destination.

Twilio delivers events to your endpoint over HTTPS through the Twilio proxy delivery service, which signs every outbound request with the X-Twilio-Signature header. Validate the signature with the request validation libraries to confirm requests originated from Twilio.

Twilio sends requests with the User-Agent header value TwilioProxy/1.1, from the Twilio static proxy IP ranges. For the current list of IP addresses and ranges, see IP addresses and ranges.

If your webhook URL includes basic-auth credentials, Twilio removes them from the URL before delivery and sends them as a standard Authorization header instead. Your endpoint never sees the raw URL-embedded credentials on the wire.

Default mappings

Field	Delivered field
Event payload	Full CloudEvents JSON body

Twilio sends data to your endpoint as a JSON array of CloudEvents. Your endpoint should iterate through the events array to process all items in the payload, even when the array contains a single element.

Verification and troubleshooting

When you save or test a Webhook destination, Twilio sends a marked test event to your endpoint through the same delivery path a real event takes. Twilio does this because a webhook endpoint has no other way to prove reachability. A successful test requires your endpoint to respond with a 2xx status within 2 seconds.

To trigger a test event, open the Console and go to the Trigger Test Event utility.

Common errors

Cause	What you'll see	Fix
Endpoint unreachable or too slow (>2s)	Connectivity test fails: "could not reach the webhook endpoint"	Confirm the endpoint is publicly reachable and responds within 2 seconds
Endpoint returns 401/403	Test fails as unauthorized	Check any credentials embedded in the webhook URL
Endpoint returns a 3xx/4xx status	Test fails: "the webhook endpoint did not accept the request"	Check the URL and HTTP method
Endpoint returns 5xx, or the Twilio delivery service has an internal issue	Delivery reported as retryable in the Debugger	Check your endpoint's health. Twilio retries 5xx responses

If Twilio can't deliver events to your endpoint, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.