Announcing the Webhook Plugin: Validate your webhooks with the new webhook plugin for the Twilio CLI

Niels Swimberghe - 3/14/2023 - Twilio

This blog post was written for Twilio and originally published at the Twilio blog.

At Twilio, we heavily use webhooks throughout all of our products, but developing and testing webhooks comes with some challenges. First, you need to make your application running on localhost public, then you have to configure the webhook with your public URL, and then you have to trigger those webhooks by manually texting or calling your Twilio Phone Number. This can be cumbersome and slows down your inner devloop.

To address these challenges, Twilio Labs created the Webhook plugin for the Twilio CLI, to test your webhooks with the following benefits:

works with locally and publicly hosted applications,
works with Twilio Functions, Twilio Studio, TwiML Bins, and custom developed applications,
no need to configure the webhook URL in Twilio,
you don't have to text or call to trigger the webhook, so you're not spending time or Twilio credit.

The webhook plugin will emulate Twilio webhook requests and send them to a local or public URL of your choosing. Let's give it a try.

Provision a Twilio webhook application #

Before you can test a Twilio application by emulating webhook requests, you’ll need to have one up and running. If you already have an application with a webhook endpoint, or your own custom app that handles webhooks, you can skip this section and use your existing application.

You can find a lot of samples on Twilio CodeExchange, but to deploy Twilio apps in an instant, you can filter them down to samples with "Quick Deploy", like the SMS Auto-response sample.

First, make sure you have a Twilio Account and a Twilio Phone Number. Sign up with Twilio for free and get $20 trial credit. Then, follow these instructions to buy a Twilio Phone Number if you haven't already.

Next, open the SMS Auto-response sample in a new browser tab, select your Twilio Phone Number, and deploy the application. Once the application is deployed, click on the "Go to live application" button. At the bottom of the page, under Troubleshooting, you'll find the webhook URL for this application. Copy and paste this webhook URL somewhere so you can use it later. The URL should look something like https://hello-messaging-1111-xxxxxx.twil.io/hello-messaging.

Congratulations, you now have a Twilio application that will respond with "Hello World" when you text your Twilio Phone Number! 🎉

Install the webhook plugin for the Twilio CLI #

First, install the Twilio CLI and log in to your Twilio account if you haven't done so already. Then, in your terminal, run the following command to install the Webhook plugin:

twilio plugins:install @twilio-labs/plugin-webhook

You list the available commands in the plugin and get documentation for the commands using the --help argument:

twilio --help webhook
twilio webhook:invoke --help

You can also read the documentation in the GitHub Repository README.md file.

Now that the Twilio CLI and Webhook plugin is installed, let's test out the webhook of your Twilio application.

Test your webhook from the Twilio CLI #

First, configure the environment variable TWILIO_AUTH_TOKEN environment variable with the Auth Token you can find in the Account Info pane of the Console Dashboard page.

Then, execute the following command to emulate an SMS webhook request:

twilio webhook:invoke <YOUR_WEBHOOK_URL>

Alternatively, you can pass in the Auth Token as the --auth-token argument instead of setting the TWILIO_AUTH_TOKEN environment variable.

If you're using the SMS Auto-response sample from earlier, you will see the following output:

<?xml version="1.0" encoding="UTF-8"?><Response><Message>Hello World</Message></Response>

This is the TwiML that the sample responds with. This TwiML tells Twilio to respond with "Hello World" to incoming text messages.

The emulated request uses a set of default parameters. To override these parameters, you can use the --data-urlencode or -d argument passing in key-value pairs.

twilio webhook:invoke <YOUR_WEBHOOK_URL> -d Body="Hi, how are you doing?" -d FromCountry=CA

If your webhook handler expects HTTP requests using the GET method, you can emulate the webhook requests using the --method or -X argument.

twilio webhook:invoke <YOUR_WEBHOOK_URL> --method GET

By default, the twilio webhook:invoke command emulates an SMS webhook request, but you can emulate a voice webhook request by passing in the --type argument.

twilio webhook:invoke <YOUR_WEBHOOK_URL> --type voice

Test secured and unsecured webhooks #

For Twilio to send HTTP requests to a webhook URL, that webhook URL has to be publicly available, but this also makes it available to all of the internet. You can secure your webhook by validating the X-Twilio-Signature header that Twilio sends as part of the webhook requests. Twilio uses your Auth Token to generate the signature, so you can generate the same signature and compare them. If they are the same, the request originates from Twilio, and if not, you should reject the request. This technique is also used for TwiML Bins and Twilio Functions that are set to protected.

To test secured webhooks, you have to pass in the Auth Token (as argument or environment variable), like you did previously. This Auth Token will be used to generate the X-Twilio-Signature header which will be part of the emulated webhook request.

For unsecured webhook URLs, you can still pass in the Auth Token, but you don't have to. To not generate the signature header, you can pass in the --no-signature argument and then you also don't need to provide the Auth Token:

twilio webhook:invoke <YOUR_WEBHOOK_URL> --no-signature

The SMS Auto-response sample will respond as follows because the Twilio Function is set to protected:

» Request failed with status code 403
» twilio-cli encountered an unexpected error. To report this issue, execute the command with the "-l debug" flag, then copy the output to a new issue here: "https://github.com/twilio-labs/plugin-webhook/issues"

However, if you change the visibility of the Twilio Function to public, meaning no signature validation, then you'll get the previous TwiML response again:

<?xml version="1.0" encoding="UTF-8"?><Response><Message>Hello World</Message></Response>

Next steps #

With the webhook plugin you can test and develop your Twilio webhooks, without needing to make your application public, configuring your webhook URL, and then manually triggering the webhook event.
This tool speeds up your inner devloop, so you can develop webhooks faster.

The webhook plugin is an open-source project on GitHub, so feel free to submit any issues, send pull requests, and star it.

Another Twilio Labs project that can increase your productivity is the Twilio Dev Phone. Learn how to test your Twilio applications using the Twilio Dev Phone here, without having to switch to your physical phone.