Webhooks Overview

Twilio provides a REST API for HTTP requests from your application to the Twilio servers. This works well for actions like sending an SMS message, or placing a voice call. What happens when your application needs to respond to an event processed by Twilio? One example where your application might need to respond would be that someone makes a phone call to one of your Twilio phone numbers - what should Twilio do next?

What are Webhooks?

Twilio will send your web application HTTP (or HTTPS) requests after certain events occur - these events differ for each Twilio product. These requests are known as webhooks or callbacks. Typically, the reason that your web application would get an HTTP callback would be that something a user did should probably be handled by your web application.

For instance, after a customer hangs up on a voice call to a customer service phone number provided by Twilio, a webhook can be sent to your web application. Your web application could tag the customer service agent who handled that phone call as available, add a record to the customer's profile about the length of the call, and then prompt the customer service agent to write follow up notes.

Some Twilio products may use a different pattern to notify your application that something has occurred - for instance, in an iOS app, there may be a delegate. Typically, webhooks are used because your application does not maintain an open session or connection with Twilio - so Twilio makes an asynchronous HTTP (or HTTPS) request to your web server.

What do you do with incoming webhooks?

Some webhooks from Twilio require a response - for instance an inbound SMS message to a Twilio phone number will trigger a webhook to your web application. Your web application would need to return valid Twilio Markup Language (TwiML) to the Twilio webhook request, even if the TwiML response is simply an empty Response tag.

Other webhooks, such as one notifying your web application that a voice recording is complete, are informational. Twilio does not require a response from your web application, other than an HTTP status code of 200 (OK).

Testing Webhooks on your local development environment

Twilio webhooks require a publicly accessible URL of some kind. While you can put basic HTTP authentication on the URL for security, the URL itself must be one that Twilio can send an HTTP request. In practice, this means that using your local computer for development requires a separate step. Typically there are routers and/or firewalls between your computer and the public internet, which means that unless you use network address translation (NAT), you'll need to use separate software to create a publicly-accessible IP address that can pass requests to your local web application server.

One freely available tool to create these tunnels is ngrok. With ngrok, you can have an HTTPS URL (such as https://dc3b6xfb.ngrok.io) that tunnels requests to a web application server running locally on your own computer at a given port.

Simply install ngrok from the above link, and then run a command similar to:

ngrok http 8080

Replace 8080 in the above command with the port that your development web server is listening to - common ports are 3000, 4567, 5000, 8000, and 8080.

You will see a display from ngrok similar to the following:

Next to the forwarding label, you will see your new publicly accessible URL. Use that URL when you configure your webhooks with Twilio, and requests will be served from your local computer. Keep the ngrok command open to maintain the same domain name, however, ngrok will expire publicly accessible domain names after a length of time if you are not on a paid subscription plan.

Learn more about webhooks

There's lots more to learn about webhooks and we've put together some detailed documentation to help you dive deeper into how to use and manage them.

• Getting Started with Twilio Webhooks
• Webhooks FAQ
• Webhooks Security