--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/usage/webhooks/webhook-testing#article headline: Test webhook delivery description: Send a test webhook through a Webhook Setting to validate authentication, signing, and connection configuration before live traffic uses it. url: https://www.twilio.com/docs/usage/webhooks/webhook-testing inLanguage: en dateModified: 2026-09-07T13:32:03.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Test webhook delivery > \[!IMPORTANT] > > 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][sla] covers Public Beta products. [sla]: https://help.twilio.com/articles/115002413087-Twilio-Beta-product-support Before deploying and while debugging Settings, test them. A test sends one webhook to a URL you choose, using a [Webhook Setting][settings] you name. Without a [Webhook Rule][rules] or touching live traffic, the test exercises that authentication, signing, and connection configuration for that Setting. > \[!WARNING] > > 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. ```bash curl -X POST https://webhooks.twilio.com/v1/Webhooks/Tests \ -H 'Content-Type: application/json' \ -u {API_KEY_SID}:{API_KEY_SECRET} \ -d '{ "url": "https://api.example.com/webhooks/test", "settingId": "{SETTING_ID}", "method": "POST" }' ``` 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][auth]. 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][keys], the Setting names and the algorithm that created the signature. | | Timeout | Check [connection][conn] 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: 1. Install and set up [ngrok][]. 2. Run a command similar to: ```bash ngrok http 8080 ``` If successful, your command line displays results similar to the following: ```bash ngrok by @inconshreveable (Ctrl+C to quit) Session Status online Account (Plan: Free) Version 2.3.40 Region United States (us) Web Interface http://127.0.0.1:4040 Forwarding http://6e81-2601-1c0-6100-5087-309b-c292-5e5f-1f.ngrok.io -> http://localhost:3000 Forwarding https://6e81-2601-1c0-6100-5087-309b-c292-5e5f-1f.ngrok.io -> http://localhost:3000 Connections ttl opn rt1 rt5 p50 p90 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][ngrok-free] that could impact your testing. Before testing, review those limits. ## What's next? * [Configure webhook rules][rules], to put a tested Setting into service * [Track webhook rule changes][operations], to confirm the rule went live * [Configuration API FAQs][faq] [auth]: /docs/usage/webhooks/webhook-auth-profiles [conn]: /docs/usage/webhooks/webhook-settings#connection [keys]: /docs/usage/webhooks/webhook-shared-keys [rules]: /docs/usage/webhooks/webhook-rules [settings]: /docs/usage/webhooks/webhook-settings [operations]: /docs/usage/webhooks/webhook-operations [faq]: /docs/usage/webhooks/webhook-configuration-faq [ngrok]: https://ngrok.com/docs/getting-started [ngrok-free]: https://ngrok.com/docs/pricing-limits/free-plan-limits