--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/data-destinations/destination/webhook#article headline: Webhook destination description: Learn how to send event data to a custom HTTP webhook endpoint. url: https://www.twilio.com/docs/data-destinations/destination/webhook inLanguage: en dateModified: 2026-11-04T17:24:28.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Webhook destination > \[!IMPORTANT] > > 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](/docs/data-destinations#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 [Sign up](https://airtable.com/appaJfyV6LiIFMxuP/pagIaOAtKsQVxTfdW/form) Get early access to native destinations for data warehouses, observability tools, and event pipelines. ## Eligible events Webhook has no restriction: all [Event Types](/docs/events/event-types-overview) are eligible for delivery. In the IE1 region, only [Voice Insights](/docs/events/event-types-overview#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 > \[!NOTE] > > See [Set up a destination](/docs/data-destinations/destination-setup) 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: 1. Gather the settings listed in [Destination settings](#destination-settings). 2. In the Twilio Console, go to **Data** > **Data Destinations** > **Destinations** > **Add destination subscription**. 3. 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](/docs/data-destinations/api-quickstart#create-a-destination). ```text title="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`` | 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. ```json title="Example request body" { "destinationType": "webhook", "name": "My Webhook destination", "config": { "url": "https://example.com/webhooks/twilio" } } ``` ## 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](/docs/usage/security#validating-requests) 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](/docs/iam/twilio-editions/twilio-static-proxy#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](https://github.com/cloudevents/spec/blob/v1.0/spec.md). 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](/docs/usage/troubleshooting/debugging-your-application) | 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](/docs/usage/troubleshooting/debugging-your-application) (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error. ## Additional resources * [Destinations overview](/docs/data-destinations/destinations-overview) * [Set up a destination](/docs/data-destinations/destination-setup) * [Event types reference](/docs/events/event-types-overview)