Here are some commonly asked questions about webhooks and inbound requests.
Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs, like Twilio.
Learn more on this glossary page: What is a Webhook?
Each type of event (such as an incoming text message, or a phone call status change) sends a webhook with a format that corresponds to that type.
For incoming phone calls, Twilio will make an HTTP request to your server that expects TwiML as a response. This HTTP request may either be a GET or a POST. Typically, you will want those HTTP requests to be encrypted with TLS, and sent over an HTTPS connection.
For inbound text messages, Twilio will send an HTTP POST request to your server with a body that uses the application/x-www-form-urlencoded encoding. View the list of parameters sent in that request.
Your web application will respond to a Twilio webhook differently, depending on what type of event it is. If you are receiving a webhook for an inbound text message, your application would respond with TwiML for Programmable SMS. For an inbound voice call, your application would produce TwiML for Programmable Voice.
Other events may simply require that your web application responds with a simple HTTP 200 OK - for instance, a Programmable Voice status callback webhook. This is typically for events where Twilio is informing your web application that an event has occurred but is not expecting interaction.
Twilio will send an X-Twilio-Signature HTTP Header with all webhooks. This signature uses your account's auth token to create a digital signature from the content of the request (the parameters being sent via either the GET or POST method). To verify that an inbound request comes from Twilio, use the Twilio Server-Side SDKs to validate the request for you with the RequestValidator.
Find more security information and tutorials for validating inbound webhooks on the Webhooks Security page.
There are a couple of different options - the first is to mimic the incoming Twilio request using a tool like Paw or Postman that lets you easily send HTTP requests to your endpoint. This is very helpful for debugging locally on your own computer.
Next, Twilio provides a Debugger as part of the Twilio Console. The Debugger will list any errors that Twilio finds when it sends a webhook to your application. For more about the Debugger, see this step-by-step guide to Debugging Webhooks.
If you would like to view historical data about errors or warnings when Twilio calls your webhook, you can use the Monitor REST API to retrieve alerts. You may also set up Monitor Alert Triggers to notify you when an error or warning occurs.
Last, Twilio also provides a Request Inspector in the Console for each Voice Call. This Request Inspector is at the bottom of the call record in the Call Logs section of the Console, which can be found under Programmable Voice, and then in the Calls Section.
The request inspector will show the exact HTTP request that Twilio made, along with the HTTP response that your web application provided. These logs are kept for 30 days.
For more about the Request Inspector, as well as other tips for debugging, see this Support Article for Debugging your application.
Twilio uses a pool of IP addresses to send webhook requests. As such, there is not a specific range of IP addresses that you should allow for Twilio webhooks. Instead, we suggest that you consider placing some servers in a DMZ and proxying the Twilio webhook request through those servers to your application servers.
For more, see this Support Article about Which IP addresses will Twilio's requests come from?
You can use ngrok or another tool to set up a tunnel between a web server running on your local computer, and a publicly accessible web URL that you can provide to Twilio to use for webhooks.
For directions to set up ngrok with your own environment, follow one of these tutorials:
Twilio Regions enable you to isolate the processing of your Twilio communications to a specific geographic location. If your applications handle traffic in multiple regions you may need to know which one was used for a given webhook. For this purpose, all webhooks will contain an HTTP header X-Home-Region containing the specific region.
Example header: X-Home-Region: us1