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

Webhooks FAQ

Here are some commonly asked questions about webhooks and inbound requests.

What is a webhook?

what-is-a-webhook page anchor

Webhooks are user-defined HTTP(link takes you to an external page) 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?

Where do I find the specifications for inbound HTTP requests to my server?

where-do-i-find-the-specifications-for-inbound-http-requests-to-my-server page anchor

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.

How does my server respond to Twilio webhooks?

how-does-my-server-respond-to-twilio-webhooks page anchor

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. Inbound faxes would respond with TwiML for Programmable Fax(link takes you to an external page).

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.

How do I validate that incoming webhooks are sent from Twilio?

how-do-i-validate-that-incoming-webhooks-are-sent-from-twilio page anchor

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.

How do I debug an incoming webhook?

how-do-i-debug-an-incoming-webhook page anchor

There are a couple of different options - the first is to mimic the incoming Twilio request using a tool like Paw(link takes you to an external page) or Postman(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page).

What IP addresses does Twilio use to send requests?

what-ip-addresses-does-twilio-use-to-send-requests page anchor

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(link takes you to an external page)?

How do I test webhooks with my local environment?

how-do-i-test-webhooks-with-my-local-environment page anchor

You can use ngrok(link takes you to an external page) 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:

What Twilio region is processing my request?

what-twilio-region-is-processing-my-request page anchor

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

Rate this page: