Webhook connection overrides
To let your app know when events like receiving an SMS message or incoming phone call happen, Twilio uses HTTP callbacks (webhooks). When the event occurs, Twilio makes an HTTP POST or a GET request to your webhook URL. The Twilio request includes details of the event such as the incoming phone number or the body of an incoming message.
Twilio conforms to the standard generic URI or URL syntax.
Configure connection behavior per URL instead
Connection overrides apply to a single webhook URL at a time. To set timeouts, retries, and edge zones once and apply them to every webhook matching a URL pattern, use the Webhooks configuration API. When a Webhook Rule applies a Setting to a webhook, that Setting's connection configuration takes precedence over any override in the URL.
To override the default webhook connection settings on a per-request basis, append the overrides to your webhook URL as a fragment. With override settings, you can specify:
- To improve support of intermittent network issues between Twilio and your server, set longer timeouts.
- To speed up failover to a fallback URL in the case of an outage on your server, set shorter timeouts.
- To set how webhook connection retries trigger, set how your webhook handles failures or timeouts.
- To direct your HTTP callback origin, set the exiting Twilio Edge.
- To improve retry completion, set the total timeout limit.
- If your server requires SNI for a proper TLS handshake, use Server Name Indication (SNI).
Connection overrides travel in the URL fragment, not in the query string.
- The fragment contains key-value pairs.
- A
#starts the fragment, and so precedes the first key-value pair. - Each key-value pair separates its key and value with a
=, and an&separates one pair from the next. - When you validate signatures from Twilio webhooks, omit the fragment. Twilio doesn't include the fragment in the signature computation, so leave it out of yours.
https://example.com/foo#ct=500&rt=1000&tt=15000&rc=2&rp=4xx,5xx,ct,rt&sni=y&e=dublin,sydney
Info
Voice webhooks that Twilio retries don't appear as separate requests in the Request Inspector section of a call's log page in the Console.
The following table details all supported overrides:
| Parameter | Key | Accepted values | Default | Notes |
|---|---|---|---|---|
Connect Timeout |
| Any integer from |
| The time in milliseconds that Twilio waits to establish its TCP connection to your server. |
Read Timeout |
| Any integer from |
| The time in milliseconds that Twilio waits for each HTTP response packet after sending the webhook request. |
Total time |
| Any integer from |
| The total time allowed for all timeouts including retries. |
Retry count |
| Any integer from |
| The number of attempts Twilio makes to retry the webhook should it fail. Set the Retry policy ( |
Retry policy |
|
|
| The type of failure that prompts the webhook to retry. |
SNI |
|
|
| When set to |
Edge Location |
|
| The Twilio edge location from which webhooks start. This value can be a single entry or a comma-separated list. |
Retry policy takes one or more of the following values.
4xxretries on any 4xx response from your web server.5xxretries on any 5xx response from your web server.ctretries on TCP connect or TLS handshake failure.rtretries on no response received within read timeout from your web server. Twilio doesn't retry partial responses.allretries on all of the previous types.
You can also pass as a list of comma-separated values: rp=ct,rt.
The Twilio edge location value can be a single entry or a comma-separated list. Twilio moves through the list with each retry.
If you enable Static Proxy, Twilio ignores the e parameter.
Twilio progresses through edge location in this order:
- Twilio Interconnect Edge, if specified in
e=. - Static Proxy, if enabled.
- Public Edge, if specified in
e=. - Default Edge.
Edge IDs that end in the -ix suffix, such as ashburn-ix, are Interconnect edges.
Interconnect edges require the following:
- You configured the URL or IP address that the webhook request targets on your Interconnect.
- You specify one of the Interconnect edges.
Without these requirements, the webhook traverses the public internet.
To distinguish retry attempts, use the HTTP header I-Twilio-Idempotency-Token.
Limit on Voice Call requests
Due to the real-time nature of voice calls, Twilio imposes a hard upper timeout of 15 seconds on all call-related HTTP requests. This hard limit overrides any other overrides on call-processing requests for a good end-user calling experience.
Other product- and resource-related timers might supersede these timers. To help you determine appropriate settings for your use case, see your product documentation.
https://example.com/foo?query=123#ct=1000
Wait one second to establish a connection.
https://example.com/foo?query=123#ct=1000&rt=1000
Wait one second to establish a connection. Wait one second for data to return.
https://example.com/foo?query=123#rt=5000&rp=ct,rt
Retry both connection and read timeouts. Wait five seconds for data to return.
https://example.com/foo?query=123#e=ashburn,umatilla
Retry on edge failures. Try Ashburn, then Umatilla.
https://example.com/foo?query=123#rc=2&ct=1000
Retry connection failures. Wait one second to establish a connection. Retry two times only.
You can override connections on all product webhooks except for Twilio Conversations and Twilio Frontline. You can specify the overrides in webhook URLs in both the API resource properties and TwiML attributes.
If you have trouble implementing a connection override, contact Twilio support for help.