Test TwiML Bins using twilio-cli

With the Twilio Labs Webhook Plugin you can simulate webhook events. These will not result in actual HTTP requests made from Twilio but instead are HTTP requests made from your machine that pass mock data that has a similar shape to the data Twilio would pass in a request.

Setup

If you don't have twilio-cli installed yet, make sure to install it first and log in using twilio login.

After setting up twilio-cli you'll need to install the Webhook Plugin:

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

Usage

Once you have the Webhook Plugin installed, you can use the twilio webhook:invoke command to simulate a webhook event to the URL that you pass:

twilio webhook:invoke <your-twiml-bin-url>

An example with a TwiML Bin would look like this:

twilio webhook:invoke https://handler.twilio.com/twiml/EHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Because TwiML Bins validate the X-Twilio-Signature header of a request, you'll have to either have the valid Auth Token for your account stored as an environment variable with the name TWILIO_AUTH_TOKEN, or pass in the Auth Token using the --auth-token argument. This Auth Token has to match the Account SID of your CLI profile & TwiML Bin. Otherwise, you can change the Account SID by using the --account-sid flag.

Once you execute your command, you'll see the TwiML response from your TwiML Bin. For example:

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

If you also want to check the HTTP response headers, you can use the -i flag.

Simulating different events

By default, the twilio webhook:invoke command will simulate an SMS event. You can change the type by using the --type flag.

For example the following will simulate a phone call request instead:

twilio webhook:invoke <your-url> --type=voice

If you want to modify some of the mock values that are being passed, for example to change the body of an incoming message you can use the -d flag:

twilio webhook:invoke <your-url> --type=sms -d Body="Ahoy there!"

If you want to learn more about the options you can pass into the Webhook Plugin, you can run twilio webhook:invoke --help or visit the GitHub repository.