With Twilio’s Programmable Voice platform, you can make, receive and monitor calls around the world using the Voice API that developers rely on. You can add a dependable, high-quality, intuitive calling experience to your applications using just a few lines of code.
However, if you have worked with APIs or other HTTP connections, you probably have struggled at times with intermittent network issues that can cause application errors. Maybe you want to wait longer for a connection, or possibly you want to failover faster? You may want redundancy through a different Edge Location? And who wouldn’t want a way to make their callbacks retry if they fail? Now, Twilio allows you to customize your HTTP callbacks (webhooks) to meet your needs!
We are pleased to announce that we have enhanced the existing Programmable Voice platform for HTTP callbacks (webhooks) allowing you to easily override our default connection settings, giving you simple and flexible control. These Connection Override parameters will 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 (Yes, retries!) on failures/timeouts
- Total timeout budget 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
- Egress Twilio Edge location for your HTTP callback (Beta)
If your Twilio web applications are hosted on servers located on the Western half of the US, you can benefit from having webhooks egress via our West Coast edge location like Umatilla (Oregon), as the shorter distance should result in a faster response time. You can also set up a retry attempt to egress from our East Coast datacenter in Ashburn (Virginia), so you have redundancy to avoid possible intermittent local issues. Lastly, you can couple these retries with a lower connection timeout of 3 seconds, if your typical response times are less than the default 5 seconds, which could lead to a better user experience.
These new HTTP callbacks Connection Overrides will be passed on a per webhook URL basis in the form of URL "fragments". These fragments will contain key-value pairs; key and value are separated by = and key value pairs are separated by &. The 1st key-value pair start with #.
The complete list of new Connection Override parameters supported are detailed below:
Timeout in ms for TCP connect to your webserver
|Read Timeout (rt)||
Amount of time in ms to wait for the initial HTTP response packet, or time between individual response packets
|Total time (tt)||
Total time allowed for all timeouts including retries
|Retry count (rc)||
Number of retry attempts
|Retry policy (rp)||
Type of failure to retry on
Enable/disable SNI for all requests, or use the current behavior
Edge location(s) or region(s) on which our HTTP callbacks will egress from (Public Beta)
Where are these HTTP callbacks connection overrides available?
You can add HTTP callbacks connection overrides on a per webhook URL basis in: the API resource properties and TwiML attributes, these are initially supported for Voice, see full details in user docs here.
Make an HTTP request to
https://example.com/foo?query=123, with a connection timeout (time to wait for the connection to be established) of 1 second.
In this case, if there is no response, the request will fail after a total of 2 seconds (two attempts to connect) and will throw a 502 error with a 11205 Twilio error notification logged to your debugger.
A setting like this would be appropriate if your typical network performance gives response times below 1 second, and you wanted to fall through to your failover settings more quickly than the default of 5 seconds per attempt.
Retry twice on failure (for a total of three attempts to connect), using a 3 second connect timeout, and a 9 second read timeout.
In this scenario, if there is no response in 3 seconds, we will retry, then if still no response, again at 6 seconds. If all 3 attempts fail to get a response, timeout after 9 seconds (instead of waiting until the default 15 seconds).
Similarly to example (1), this might be a good way to use the settings if you normally see response times under 3 seconds, but want to account for intermittent network issues, and also a somewhat quicker failover. As you can see, these settings allow you to customize your application to your specific performance and needs.
Retry on failure using alternate Twilio Edge Locations, and the default connect timeout of 5 seconds per attempt. First attempt goes out over ashburn (Virginia), second attempt goes out over umatilla (Oregon).
This scenario is similar to what was described in our earlier paragraph; it adds geographic redundancy by trying multiple Edge Locations, in case of temporary network issues at the primary location. It is also possible to add multiple iterations of these locations.
Let’s Get Started!
If you are already using Programmable Voice, and are familiar with HTTP callbacks, feel free to start using these new parameters in your Applications. Full documentation on Twilio Webhooks.
We are very proud to bring you these enhancements to the Twilio Programmable Voice platform (see user documentation), and hope that they help to provide you and your customers a more resilient, reliable experience. We can’t wait to see what you build!
If you have any questions or need help with anything Twilio, don’t hesitate to reach us at email@example.com.
This post was authored by Annie Benitez Pelaez & Bill Harrison.