Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Getting Started with Twilio Webhooks

Ready to get started with Twilio webhooks? Our first recommendation is to watch this video on what webhooks are! Prefer to read about them instead of watching a video? Check out this glossary entry: What is a Webhook?

Next, you can follow along with these directions, as we show you how to receive Twilio webhooks with your web application.

This getting started guide is not specific to a certain product at Twilio or to a particular language or platform. We do have language-specific step-by-step tutorials for common webhooks use cases (such as Responding to Incoming Phone Calls, or Tracking Delivery Status of Messages). Other tutorials may be found by choosing the Twilio product from the complete list of tutorials.

Finding the right webhooks

The first step in the process is to find the right webhooks for your application. Specific information about webhooks by product is on these pages:

Other Twilio products (such as Chat and Authy) also have webhooks for certain events.

In addition to product-specific webhooks, your web application may receive webhooks from Twilio for events such as an error in TwiML returned by your application, or exceeding a certain number of text messages sent per month. For these webhooks, see these pages in the documentation:

Of course, your project may not need all of these webhooks - but you may be able to add some interesting functionality by using them!

Responding to webhooks

The next step is to map out how you will respond to each webhook. Some Twilio webhooks require a response, typically in Twilio Markup Language (TwiML). The TwiML you send back to the webhook will vary based on what product you are using:

Other Twilio webhooks are informational, and simply require a standard HTTP 200 OK response. This acknowledges that the webhook was received by your web application.

Use mock webhook requests for development

Once you have identified the webhooks you are planning to use, it's time to write some code! For ad-hoc testing purposes during development, you may find it worthwhile to set up mock HTTP requests to your application. We suggest either using a command-line tool like curl, or a desktop application like Postman.

Use the sample webhook requests found in the Twilio documentation as starters for your own requests, or send Twilio webhooks to a service like RequestBin to capture the HTTP request being sent.

Create automated tests for webhooks

After doing some initial validation of your code, you can write automated tests using your preferred testing framework. Once you deploy your application, you can check the Twilio Debugger for errors when a webhook is sent to your application. Those HTTP requests would make excellent candidates for additional tests for your web application framework.

For test-driven development (TDD), you may consider swapping the order of this step and the previous step.

Run your application on a public URL

Twilio needs to send webhook requests to a publicly available URL. There are two main ways of approaching this - the first is to deploy your web application code to a development or test server that is reachable from the public internet. The second way is to use an HTTP tunneling tool like ngrok to set up a public URL for your application (like https://n4f4j12.ngrok.io/) that maps to a web application server running locally on your computer.

In some cases, ngrok or other http tunnels may be blocked by your internal network's firewalls. In those cases, you should set up a development or testing server to use with Twilio before deploying your webhook project to a production environment.

For more about using ngrok to develop webhooks locally, see:

Configure your public URL with Twilio

Now, Twilio will need to know what URL to send webhooks to. For Twilio phone numbers, you can set the webhook URL for inbound voice calls, SMS messages, or inbound faxes through the Twilio Console.

For other webhooks, such as the delivery status for SMS messages, you will need to set the Callback URL either when you send the message through the REST API or when you provide TwiML as a response. Typically, this is named the callback URL parameter or the status callback URL parameter.

For specific information about how to set the callback URL, see the webhook documentation for that product or type of webhook.

Validate that webhook requests are coming from Twilio

Once you have Twilio sending requests to your web application, you may start validating that your incoming webhooks are actually from Twilio. This ensures that third parties can't issue requests to your webhook URL. Twilio signs each HTTP request to your web application with an X-Twilio-Signature HTTP header using your Twilio account key.

See the guide to Webhooks Security for more, and read the validating Twilio requests section of the security documentation.

Also, you will need to update your integration tests, if the path they are testing goes through your validation process. One approach would be to sign your HTTP requests with a made-up Twilio account key, and then use that same key to validate requests in the integration test.

Many test frameworks can set environment variables for test mode (as opposed to production), and keeping account credentials outside of your code is also a best practice.

Test your webhooks with live traffic

Everything should work now, but it's time to try some live traffic out! This will depend on which webhooks you are using, but you can start making phone calls to your Twilio number, sending text messages, or whatever else you have built. Try to exercise as many corner or edge cases as possible with your application, so that you can see if there were any assumptions left out of your unit or integration tests. Go in and add those edge cases to your automated tests, while you are doing manual testing.

Promote your web application to staging and production

Now you can start the process of promoting your web application to a staging environment, and then to production. As you enter each step, update the callback URL you use with Twilio to ensure that the testing you are doing goes to the correct environment.

Double check that your production Twilio phone numbers are pointing to production web application environments. Similarly, make sure that the webhooks are being received in production, and network rules don't need to be changed on the firewall.

Test your webhook with SSL enabled, and the certificates you use in production, to ensure that everything works correctly. Twilio webhooks will not work on HTTPS endpoints with self-signed SSL certificates - for more, see the guide to Webhooks Security.

Congratulations! Your web application is in production, and ready to respond to Twilio webhooks! If you run into problems, please visit the Webhooks FAQ.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.