Webhooks Overview
Twilio uses webhooks to notify your web application when events occur, such as an incoming phone call to one of your Twilio phone numbers. While the Twilio REST API handles requests from your application to Twilio, webhooks handle the reverse: requests from Twilio to your application in response to events Twilio processes.
Webhooks, also called callbacks, are the HTTP (or HTTPS) requests that Twilio sends to your web application after certain events occur. These events differ for each Twilio product. Typically, your web application receives a webhook because a user did something that your application should handle.
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.
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 a 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).
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 (like https://dc3b6xfb.ngrok.io) that tunnels requests to a web application server running locally on your own computer at a given port.
To create a tunnel with ngrok, follow these steps:
- Install ngrok
- Run a command similar to:
ngrok http 8080
If your development web server uses a different port, replace 8080 with that port. Common ports include 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.
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.