Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Webhooks Security


Ensuring secure communication between your application and Twilio is essential. There are several layers of security and validation that you can build into your web application for handling Twilio webhooks - let's review each of these.


HTTPS/TLS

httpstls page anchor

The first step you should take to secure your web application is to ensure that you are using HTTPS for your web application's endpoint. Twilio will not connect to an HTTPS URL with a self-signed certificate, so use a certificate from a provider such as Let's Encrypt(link takes you to an external page).

Twilio can use the HTTP protocol for callbacks - for instance, if you are working on a development environment that does not have SSL certificates installed. On your Twilio project's Settings page in the Console, the SSL Certificate Validation setting enforces validation on webhooks.

(warning)

Warning

Be aware Twilio strongly recommends against pinning certificates. This is an outdated practice as certificates can be rotated at any time.

Here is the list of supported TLS ciphers for callbacks.(link takes you to an external page)


Validating Signatures from Twilio

validating-signatures-from-twilio page anchor

Your web application should verify that Twilio is the service that sent a webhook before responding to that request. This is important for securing sensitive data, and to protect your application and servers from abuse.

Twilio will sign all inbound requests to your application with an X-Twilio-Signature HTTP header. Twilio uses the parameters sent in the webhook (either GET or POST) and the exact URL your application supplied to Twilio to create this signature. The signature uses the HMAC-SHA1 hashing algorithm with your Twilio account's auth token as the secret key.

Your application can verify that this signature is correct using the server-side Twilio SDKs (see examples below). You will need your account's auth token, the value of the X-Twilio-Signature HTTP header Twilio passed to you, the URL Twilio sent the webhook to and all parameters sent by Twilio.

(error)

Danger

The parameters included in webhook events vary by channel and event type and are subject to change in the future. Twilio will occasionally add new parameters without advance notice. When integrating with webhooks, your implementation must be able to accept and correctly run signature validation on an evolving set of parameters. We strongly recommend using the provided signature validation library from a Twilio SDK and not implementing your own signature validation.

(information)

Info

When validating the signature on a WebSocket request, note that the header parameter name will be all lowercase: x-twilio-signature.

Validate Signature of Request

validate-signature-of-request page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby

_26
// Get twilio-node from twilio.com/docs/libraries/node
_26
const client = require('twilio');
_26
_26
// Your Auth Token from twilio.com/console
_26
const authToken = process.env.TWILIO_AUTH_TOKEN;
_26
_26
// Store Twilio's request URL (the url of your webhook) as a variable
_26
const url = 'https://mycompany.com/myapp';
_26
_26
// Store the application/x-www-form-urlencoded parameters from Twilio's request as a variable
_26
// In practice, this MUST include all received parameters, not a
_26
// hardcoded list of parameters that you receive today. New parameters
_26
// may be added without notice.
_26
const params = {
_26
CallSid: 'CA1234567890ABCDE',
_26
Caller: '+12349013030',
_26
Digits: '1234',
_26
From: '+12349013030',
_26
To: '+18005551212',
_26
};
_26
_26
// Store the X-Twilio-Signature header attached to the request as a variable
_26
const twilioSignature = 'Np1nax6uFoY6qpfT5l9jWwJeit0=';
_26
_26
// Check if the incoming signature is valid for your application URL and the incoming parameters
_26
console.log(client.validateRequest(authToken, twilioSignature, url, params));

For more, including code samples and a description of how Twilio signs requests to your web application see this page on how to validate Twilio requests. The exact algorithm that Twilio uses to calculate the signature header (including whether or not the port number is used) is described in detail.


Tutorials for Validating Incoming Twilio Requests

tutorials-for-validating-incoming-twilio-requests page anchor

Once you've decided to add Twilio request validation to your application, you can follow one of our handy tutorials for your chosen language and web application framework. Do you use something we don't have on this list? Let us know, and we'll try and point you in the right direction.


Webhooks and IP Addresses

webhooks-and-ip-addresses page anchor

Twilio uses a cloud architecture to provide services, and as such, does not have a fixed range of IP addresses that issue webhooks.

When designing your network architecture, you may wish to have one set of servers and a load balancer in a DMZ that receive webhook requests from Twilio, and then proxy those requests to your private network.

For more about Twilio and IP Addresses, please see this support Article: All About Twilio IP Addresses(link takes you to an external page)


Twilio supports HTTP Basic and Digest Authentication. This allows you to password-protect the TwiML URLs on your web server so that only you and Twilio can access them. You may provide a username and password via the following URL format.


_10
https://username:password@www.myserver.com/my_secure_document

For more about how Twilio uses HTTP Authentication for webhook requests, please visit the Security documentation.


Rate this page: