Choose webhook edge zones
Public Beta
The Webhooks configuration API, including the Webhook Settings and Webhook Rules resources, has been released as a Public Beta product. Before Twilio declares this product as Generally Available, the information contained in this document might change. Twilio might implement additional features or change others. No Twilio SLA covers Public Beta products.
An edge zone is a named geographic region Twilio delivers webhooks from. Configuring zones on a Webhook Setting keeps webhook egress in the regions you choose, which matters when your endpoint restricts inbound traffic by region or when you want to shorten the network path.
When a Setting omits edgeZones, every zone is eligible and Twilio selects freely.
A zone contains one or more edge locations, each a physical point of presence. Twilio picks the best available location within a zone at delivery time.
| Identifier | Use in configuration | |
|---|---|---|
| Zone | A stable zone ID from the catalog | Yes — this is what edgeZones.zones accepts |
| Edge location | {IATA}-{n}, such as DUB-1 | No — observable only |
Edge location IDs appear in the X-Twilio-Edge-Location response header, so you can see which point of presence handled a request. They aren't valid in a Setting.
This read-only endpoint returns the catalog with each zone's locations nested inside it. Call it to get valid zone IDs before you create a Setting.
1curl -X GET https://webhooks.twilio.com/v1/Webhooks/EdgeZones \2-u {API_KEY_SID}:{API_KEY_SECRET}
Each zone carries an id to use in configuration, a friendlyName, a description with routing guidance, and an edgeLocations array of the points of presence currently active in it.
The endpoint paginates with pageSize and pageToken.
edgeZones takes a priority-ordered list. Twilio routes to the first zone in the list with an available point of presence.
| Property | Type | Necessity | Description |
|---|---|---|---|
zones | array | required | Zone IDs in priority order. |
allowZoneFallback | boolean | optional | Whether Twilio may use a zone outside the list. Defaults to false. |
1curl -X POST https://webhooks.twilio.com/v1/Webhooks/Settings \2-H 'Content-Type: application/json' \3-u {API_KEY_SID}:{API_KEY_SECRET} \4-d '{5"friendlyName": "EU-only delivery",6"auth": { "source": "INLINE", "value": { "scheme": "NONE" } },7"edgeZones": {8"zones": ["{PRIMARY_ZONE_ID}", "{SECONDARY_ZONE_ID}"],9"allowZoneFallback": false10}11}'
allowZoneFallback decides what happens when none of your configured zones have an available point of presence.
false, the default: delivery fails rather than routing through a zone you didn't configure. Choose this when routing outside your chosen regions would breach a data residency requirement.true: Twilio falls back to any available zone. Choose this when delivery matters more than the egress region.
A restrictive zone list can drop webhooks
A single zone with allowZoneFallback set to false means webhooks fail whenever that zone is unavailable. List more than one zone in priority order, or enable fallback, unless a strict residency requirement rules it out.
Configuring edgeZones on a Setting isn't the same as the #e= URL connection override, which names a specific edge location per request. When a Rule applies a Setting to a webhook, the Setting takes precedence over a URL override on that request.
- Override webhook connections, to set an edge per request instead
- Configuration API FAQs