Webhooks (HTTP callbacks): Connection Overrides

Twilio has implemented URL extensions, that can be added to the standard HTTP webhook URL. These extensions give you the ability to override Twilio's default HTTP callback connection settings on a per-request basis. The override settings allow you to specify:

• Longer timeouts to better support intermittent network issues between Twilio and your server/application
• Shorter timeouts to speed up failover (to fallback URL) in the case of an outage on your server/application
• HTTP callback connection retries on failures/timeouts
• The egress Twilio Edge for your HTTP callback
• The total timeout limit for all retries to complete
• The use of Server Name Indication (SNI) if your server/application requires SNI to ensure a proper TLS handshake for all attempts

Connection overrides will be passed on a per webhook URL basis in the form of "fragments". These fragments will contain key-value pairs; key and value are separated by = , pairs are separated by & . The 1st key-value pair start with #.

The complete list of overrides supported is detailed below:

Parameter: Connect Timeout (ct)

Valid values:

Min: 100Max: 10000

Default:

5000

Notes:

The timeout in milliseconds Twilio will wait to establish its TCP connection to your web server.

Parameter: Read Timeout (rt)

Valid values:

Min: 100Max: 15000

Default:

15000

Notes:

The amount of time in milliseconds after sending your webhook an HTTP request that Twilio will wait for the initial HTTP response packet. Also applies to the amount of time Twilio will wait between individual packets within your HTTP response.

Parameter: Total time (tt)

Valid values:

Min: 100Max: 15000

Default:

15000

Notes:

The total time allowed for all timeouts including retries. If not set, the maximum limit is enforced.

Parameter: Retry count (rc)

Valid values:

Min: 0Max: 5

Default:

1

Notes:

The number of retry attempts Twilio will make if its connection to your webhook fails. To make sure you capture the behaviors you need, make sure to set the Retry Policy ( rp ) value below accordingly

Parameter: Retry policy (rp)

Valid values:

4xx, 5xx, ct, rt, all

Default:

ct

Notes:

The type of failure to retry on:

• 4xx — Any 4xx response from your web server
• 5xx — Any 5xx response from your web server
• ct — TCP connect or TLS handshake failure
• rt — No response received within read timeout from your web server. We will not retry on partial response, e.g., missing HTTP content.
• all — All of the above.

Pass as a list of values, e.g., rp=ct,rt

Parameter: SNI (sni)

Valid values:

y, n

Default:

y

Notes:

If set to y we use SNI (default). If set to n we disable SNI.Note Only applies for secure connections (HTTPS)

Parameter: Edge Location (e)

Valid values:

ashburn, dublin, frankfurt, sao-paulo, singapore, sydney, tokyo, or umatilla ashburn-ix, frankfurt-ix, london-ix, san-jose-ix, or singapore-ix (only used with Twilio Interconnect)

Default:

ashburn

Notes:

The Twilio edge location where webhooks egress. This can be a list, and we rotate through the list as retries occur. The order of precedence for edge location is:

1. Twilio Interconnect Edge, if specified in e=.
2. Static Proxy, if enabled.
3. Public Edge, if specified in e=.
4. Default Edge.

If Static Proxy is enabled for the account, the e parameter is ignored.

The values with the -ix suffix are used for Interconnect edges. To allow webhooks to traverse your interconnect, ensure the following:

• The URL or IP address that the webhook request targets is configured on your interconnect.
• You specify one of the interconnect edges.

Otherwise, the webhook will traverse the public internet.

There will be a new HTTP header (I-Twilio-Idempotency-Token), a unique string, that you can use to distinguish retry attempts.

(1) https://example.com/foo?query=123#ct=1000

Connection timeout (time to wait for a connection to be established) of one second.

(2) https://example.com/foo?query=123#ct=1000&rt=1000

Connection timeout (time to wait for a connection to be established) of one second and a Read timeout (time to wait for data to be returned on a connection) of one second.

(3) https://example.com/foo?query=123#rt=5000&rp=ct,rt

Retry on both connect and read timeout, while also reducing the read timeout to five seconds.

(4) https://example.com/foo?query=123#e=ashburn,umatilla

Retry on failure over different edge locations. The first attempt goes out over Ashburn, second attempt goes out over Umatilla (Oregon).

(5) https://example.com/foo?query=123#rc=2&ct=1000

Retry on connection failure, but with a one-second connection timeout. If there is no connection in one second, retry twice, i.e., for a total of three attempts to connect.

Connection overrides are available on all product webhooks except for Twilio Conversations and Twilio Frontline. The overrides may be specified in webhook URLs in both the API resource properties and TwiML attributes.

If you have trouble implementing a connection override, you can reach out to our support team for help.