Choose webhook edge zones
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