Test TwiML Bins using twilio-cli

The Webhook Plugin is still in an experimental stage and part of Twilio Labs. If you find any issues, please open an issue on our GitHub repository.

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.


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


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

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"?>

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.

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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!