Guide To Twilio Webhooks Features And Best Practices

Types of Twilio Webhooks

Informational

These webhooks only expect a standard 200 ok response without a body from the application which receives the webhook notification. Unlike their response-based counterparts, Twilio’s Informational webhooks do not propagate further action.

Response-Based

When a specified event occurs, certain Twilio applications expect to get a response body from your web application, this qualifies as being response-based. Once the event is triggered, Twilio makes a GET request to your URL endpoint and expects a response in the TwiML format. The URL of the GET request will include details of the event such as the incoming phone number or the body of an incoming message — This will influence the TwiML sent as a response. Response-based webhooks are offered by Twilio’s programmable SMS & programmable voice services.

TwiML is a shortened version of Twilio Markup Language, which is a set of instructions that Twilio should execute in response to the triggered event. Twilio has helper libraries for generating TwiML syntax. Here is a great guide to getting started with the Twilio Markup Language

Configuring & Setting Up A Webhook

To receive a notification when an event occurs, you have to create a webhook notification. Twilio webhook can be configured using either the Twilio console or the REST API associated with a Twilio application.

Configuring a webhook using the REST admin API

You can wire up a webhook notification using the API associated with the Twilio Application. Each Twilio API has various ways of wiring up webhooks. The documentation for the Twilio API includes extensive information on working with their webhooks.

Aside from the webhooks for specific events, you can also pass in a Status Callback URL parameter. When this callback URL parameter is provided, Twilio sends status information about your resource. If a callback URL parameter is provided when creating an SMS resource, Twilio will send notifications to the callback URL when the message is queued, sent, or delivered. The request body of an HTTP request to Twilio’s SMS application which includes a callback URL would be similar to the block of JSON code seen below:

    {
     "Body": "This is the message Body",
     "From": "+ registered-Twilio-Number",
     "To": "+receivers-number",
     "StatusCallback": "https://your-web-hook-endpoint"
    }

Configuring a webhook using the Twilio Admin

Configuring a webhook using the console can be done in three steps:

1. Select the project you would like to associate the webhook with.
2. In your project dashboard, click on the hamburger menu by the left and select the Twilio Application, you would like to create a webhook for. Some applications require you to go to their settings to create a new webhook.
3. Click the create webhook button and select the events you want to be notified for. You must provide a publicly available URL where Twilio will send your notifications to.

Twilio Runtime Webhooks

Aside from the regular webhook associated with a particular Twilio application, Twilio has Runtime Webhooks. Users can subscribe to get notified about events that occur across their Twilio account. You can configure Twilio's Runtime webhooks to notify you once you exceed a certain billing threshold or when an error occurs within your application. You can use the runtime webhook creatively to send notifications to your team’s workspace.

HTTP Headers

The HTTP headers attached to webhook notifications will vary depending on the Twilio application in question. There are only two HTTP headers that will always be included:

• X-Twilio-Signature — Twilio signs all requests to your application with the value of this header. This header is used to verify webhook notifications
• I-Twilio-Idempotency-Token — This header is used to ensure the idempotency of Twilio webhooks. The value of this header is used to keep track of retry attempts.

Availability & Reliability

To ensure reliability Twilio allows the configuration of a fallback URL. The fallback URL will receive a request from Twilio once a fatal error occurs within your application. The request Twilio makes to the fallback URL will contain information about the error that occurred, the error code, and the error URL. Your application can respond to the request with TwiML, or a custom error message. You can configure your fallback URL to log the error that occurs and even send you an alert.

Connection Overrides

In 2019, Twilio introduced the concept of connection overrides for working with their webhooks. Connection overrides allow you to customize Twilios default connection settings to fit your needs. Connection overrides are implemented via the webhook endpoint URL and are in the form of query parameters.

The connection overrides operate on a per request basis. Using connection overrides, it is possible to increase or decrease the timeout period, set up retires for failed requests/timeouts. To wire up a connection override, you have to append the desired override key & values to your URL endpoint. The full list of override values can be found here.

Below is an example of a webhook URL with connection overrides https://connectoverride.com/foo#ct=5000&rt=3000. The URL specifies a connection timeout of five seconds & a read timeout of three seconds. Connection overrides are available for all Twilio webhook offerings.

Incoming Webhooks Verification

It is important to verify that requests to your server are originally sent from Twilio. Webhook notifications from Twilio usually contain an X-Twilio-Signature HTTP header. This header uses your accounts authentication token to create a digital signature from the content of the request using the HMAC-SHA1 hashing algorithm. You can verify a request was originally sent from Twilio by generating a hash and comparing it with the value of the X-Twilio-Signature HTTP header. Twilio provides various client libraries that have functionality for verifying requests.

Debugging Event Webhooks

To err is human and to help you figure out what error occurred, Twilio offers a console debugger. The console debugger makes it possible for users to configure a webhook. Once a webhook is configured via the console debugger, the webhook URL endpoint will receive notifications about errors and warnings that occur on the associated Twilio Account. The console debugger makes it easy for developers to trace errors that occur in an application easily. The webhook notification that the debugger sends includes a payload that contains detailed information about the error that occurred. To create a webhook using the console debugger:

1. Sign in to your Twilio console, click the hamburger menu, and select debugger under the runtime section.
2. Next, navigate to the “webhook & email triggers” tab and input the webhook URL endpoint.

Dealing with Idempotency

To achieve idempotency Twilio includes an I-Twilio-Idempotency-Token HTTP header in the request it sends to help distinguish between various retry attempts. The value of this header is a string that is unique across all retry attempts to help you take note of which webhooks you have already processed.

Delayed Processing Of Webhooks

“Queue first, Ask questions later”! It is best practice to defer the processing of your webhooks till you have sent a response to the webhook provider. In the case of Twilio, it is especially important to delay the processing because once a webhook times out, Twilio only offers a single retry attempt 15 seconds after the failure. Limited automatic retry means that dropping a webhook has a high chance of losing it completely.