Test webhook delivery

(new)

Public Beta

The Webhooks configuration API, including the Webhook Settings and Webhook Rules resources, has been released as a Public Beta product. Before Twilio declares this product as Generally Available, the information contained in this document might change. Twilio might implement additional features or change others. No Twilio SLA covers Public Beta products.

Before deploying and while debugging Settings, test them.

A test sends one webhook to a URL you choose, using a Webhook Setting you name. Without a Webhook Rule or touching live traffic, the test exercises that authentication, signing, and connection configuration for that Setting.

(warning)

Wait for the Setting to propagate first

A Setting has to finish propagating to Twilio's webhook delivery plane before it can be tested. This takes 30 to 60 seconds after you create it. A test sent within that timeframe returns a 422 error. Wait for the window to pass and retry.

Request parameters

Test requests can use the following request body parameters.

Parameter	Type	Necessity	Description
`url`	string	required	The webhook URL to send the test to.
`settingId`	string	required	The Setting whose configuration the test uses.
`method`	enum	optional	`GET` or `POST`. Defaults to `POST`.

Send a test

Before deployint your webhook, test it with the following API resource.

1curl -X POST https://webhooks.twilio.com/v1/Webhooks/Tests \
2     -H 'Content-Type: application/json' \
3     -u {API_KEY_SID}:{API_KEY_SECRET} \
4     -d '{
5           "url": "https://api.example.com/webhooks/test",
6           "settingId": "{SETTING_ID}",
7           "method": "POST"
8         }'

A 200 response means the test ran, not that delivery succeeded. To find out the result, review result.outcome.

Review the result

The resulting JSON document contains the following properties:

Property	Description
`url`	The URL that the test targeted.
`result.outcome`	How the request got received: `DELIVERED` or `FAILED`.
`result.response`	The HTTP response your endpoint returned.
`result.timing`	How long the delivery took.
`result.error`	A human-readable explanation of the error. Returned when `"outcome": "FAILED"`.
`createdAt`	When the test ran, expressed as an ISO 8601 timestamp.

The result.response property returns one of the following values:

Value	Meaning
`400`	The configuration was invalid.
`401`	The authentication failed.
`403`	The authentication failed.
`422`	The Setting hasn't finished propagating. Retry after 30 to 60 seconds.
`500`	Twilio failed while attempting the delivery. Your webhook endpoint didn't reject it.

Possible remedies can include the following:

Error	Potential Setting remedy
`401` or `403`	Check authentication. For OAuth 2.0, confirm Twilio can reach your token endpoint and that your authentication server returns a `Bearer` token.
Rejected signature	Check your validation code, not the Setting. Check that verified with the shared key, the Setting names and the algorithm that created the signature.
Timeout	Check connection configuration. Compare `result.timing` against `connectTimeoutMs` and `readTimeoutMs`.

Test in your local environment

Twilio webhooks require a public URL. While you can put basic HTTP authentication on the URL for security, Twilio needs to connect to the URL. Firewalls and network configurations can block your localhost from the internet. To use your local computer for development, you need to create a tunnel through another public URL to your environment.

To create these tunnels, use ngrok. ngrok provides an HTTPS URL (like https://dc3b6xfb.ngrok.io) that sends requests to a web app running on your computer at a given port.

To create a tunnel with ngrok, follow these steps:

Install and set up ngrok.
Run a command similar to:
ngrok http 8080

If successful, your command line displays results similar to the following:

1ngrok by @inconshreveable                                                           (Ctrl+C to quit)
2
3Session Status   online
4Account          <Your name> (Plan: Free)
5Version          2.3.40
6Region           United States (us)
7Web Interface    http://127.0.0.1:4040
8Forwarding       http://6e81-2601-1c0-6100-5087-309b-c292-5e5f-1f.ngrok.io -> http://localhost:3000
9Forwarding       https://6e81-2601-1c0-6100-5087-309b-c292-5e5f-1f.ngrok.io -> http://localhost:3000
10
11Connections      ttl     opn     rt1     rt5     p50     p90
12                 0       0       0.00    0.00    0.00    0.00

Your public URL comes after the Forwarding property. When you configure your webhooks with Twilio, use that URL. Your local computer then serves the requests. To maintain the same domain name, keep the ngrok command running. ngrok implemented some monthly limits that could impact your testing. Before testing, review those limits.

What's next?

Configure webhook rules, to put a tested Setting into service
Track webhook rule changes, to confirm the rule went live
Configuration API FAQs