Rate this page:

Webhooks (HTTP callbacks): Connection Overrides

Twilio uses HTTP callbacks (webhooks) to let your application know when events happen, such as receiving an SMS message or getting an incoming phone call. When the event occurs, Twilio makes an HTTP request (usually a POST or a GET) to the URL you configured for the webhook. Twilio's request will include details of the event such as the incoming phone number or the body of an incoming message.

Twilio’s use of HTTP URLs conforms to the standard syntax of a generic URI/URL.

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 callbacks 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 (region) for your HTTP callback
  • The total timeout limit for all of the 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 are detailed below:


Valid values



Connect Timeout

Min: 100

Max: 10000


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

Read Timeout

Min: 100

Max: 15000


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.

Total time

Min: 100

Max: 15000


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

Retry count

Min: 0

Max: 5


The number of retry attempts Twilio will make if its connection to your webhook fails.

To make sure you capture the behaviours you need, make sure to set the Retry Policy( rp ) value below accordingly

Retry policy


(list of values. e.g. rp=ct,rt)


The type of failure to retry on:

- 4xx - any 4xx response from your webserver

- 5xx - any 5xx response from your webserver

- ct - TCP connect or TLS handshake failure

- rt - no response received within read timeout from your webserver. We will not retry on partial response (e.g missing HTTP content).

- all - All of the above




If set to y we use SNI for all webhooks to customer (including retry).

If set to n we disable SNI for all requests.

If parameter not set the initial request will use SNI, but the retry will not.

NOTE: only applies for secure connections (HTTPS)

Edge Location

ashburn | dublin | frankfurt | sao-paulo | singapore | sydney | tokyo | umatilla

ashburn-ix | frankfurt-ix | london-ix | san-jose-ix | singapore-ix
(only used with Twilio Interconnect)



The Twilio edge location where webhooks egress. This can be a list and we rotate through the list as retries happen.

The order of precedence for edge location: (1) Twilio Interconnect Edge if specified in (e=), (2) Static Proxy if enabled, (3) Public Edge if specified in (e=), (4) Default

If staticproxy is enabled for the account the 'e' parameter is ignored.

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

NOTE: Due to the real-time nature of voice calls, there is a hard upper timeout of 15 seconds imposed by Twilio on all call-related HTTP requests. This hard limit overrides any of the timers described above on call-processing requests, and is present to help to ensure a good end-user calling experience.

There are also other product and resource-related timers which may supercede these timers; please review your product documentation to help you determine appropriate settings for your use-case.



Connection timeout (time to wait for a connection to be established) of 1 sec


Connection timeout (time to wait for a connection to be established) of 1 sec and a Read timeout (time to wait for data to be returned on a connection) of 1 sec


Retry on both connect and read timeout, while also reducting the read timeout to 5 seconds.


Retry on failure over different edge location. First attempt goes out over Ashburn, second attempt goes out over Umatilla (Oregon).


Retry on connection failure, but with a 1s connection timeout. If there is no connection in 1 second, retry (twice) - for a total of three attempts to connect.

Where are these Overrides Available?

Overrides may be specified in webhook URLs in both the API resource properties and TwiML attributes.

Here is the complete list of resources and attributes currently supported:

API Resource Properties:

IncomingPhoneNumber properties

(Phone Numbers / Manage Numbers / Active Numbers in Twilio Console)

  • voice_url
  • voice_fallback_url
  • sms_url
  • sms_fallback_url
  • status_callback

SipDomain properties

(Voice / SIP Domains / Domains / in Twilio Console)

  • voice_url
  • voice_fallback_url
  • voice_status_callback_url

TwiML App properties

(Voice / TwiML / TwiML Apps / in Twilio Console)

  • voice_url
  • voice_fallback_url
  • status_callback

Calls resource (Initiating a call using API)

  • url
  • fallbackUrl
  • statusCallback

Messages resource (Creating a message using API)

  • statusCallback

Messaging Services resource (Creating and configuring Messaging Service)

  • inboundRequestUrl
  • fallbackUrl
  • statusCallback

Rooms resource (Creating and configuring Programmable Video Rooms / in Twilio Console)

  • statusCallbackUrl

TwiML attributes:

<Dial> attributes

  • action
  • recordingStatusCallback

<Client> <Number> <Sip> attributes

  • url
  • statusCallback

<Enqueue> attributes

  • waitUrl
  • action

<Queue> attributes

  • url

<Gather> attributes

  • action
  • partialResultCallback

<Pay> attributes

  • action
  • statusCallback

<Record> attributes

  • action
  • recordingStatusCallbackMethod
  • transcribeCallback

<Redirect> attributes

  • Noun
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more