--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/usage/webhooks/webhook-configuration#article headline: Webhooks configuration API description: Configure how Twilio authenticates, signs, and delivers your outbound webhooks per URL using Webhook Settings and Webhook Rules. url: https://www.twilio.com/docs/usage/webhooks/webhook-configuration inLanguage: en dateModified: 2026-09-07T13:32:03.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Webhooks configuration API > \[!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 With the Webhooks configuration API, you control how Twilio authenticates, signs, and delivers each outbound webhook, based on the webhook's URL. Use it to authenticate Twilio to your endpoints with OAuth 2.0, Basic, or Digest credentials, to sign requests with a key you manage instead of your account authentication token, and to set the timeouts, retries, and edge zones Twilio uses when delivering a webhook. ## Base URL ```http https://webhooks.twilio.com/v1/Webhooks ``` If you onboarded to the private beta, that API is at `preview.twilio.com` and remains available to your account. It's a separate API, so see [I onboarded to the private beta][faq] before you migrate. ## Authentication Every request uses [HTTP basic authentication][basic-auth]. Use an [API key][api-keys] SID as the username and the API key secret as the password. ```bash curl -X GET https://webhooks.twilio.com/v1/Webhooks/Settings \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` You can use your account SID and authentication token instead, but limit that to local testing. ## The resource model Two resources do the main work, and the rest support them. | Resource | What it holds | | ------------------------ | ----------------------------------------------------------------------------------------- | | [Settings][settings] | One complete delivery configuration: authentication, signing, connection, and edge zones. | | [Rules][rules] | A URL match pattern, and the Settings to apply to webhooks matching it. | | [AuthProfiles][auth] | Reusable credentials that several Settings can share. | | [SharedKeys][keys] | Signing keys used to sign webhook requests. | | [Operations][operations] | The status of an in-flight Rule change. | | [Tests][testing] | A single test delivery against a Setting. | | [EdgeZones][zones] | The catalog of edge zones you can deliver from. | A Setting on its own changes nothing. Twilio applies a Setting only when a Rule points a matching webhook URL at it. ## How Twilio applies a configuration When Twilio sends a webhook, it compares the destination URL against your Rules, applies the Setting that the winning Rule names, and delivers the request using that Setting's authentication, signing, connection, and edge zone configuration. If no Rule matches, Twilio sends the webhook with no Setting applied: Twilio doesn't authenticate itself to your endpoint, it signs the request with your account authentication token using `HMAC_SHA1`, and it uses default connection behavior. ## Quickstart This creates a configuration that signs every webhook from your account with a key you control. 1. Create a SharedKey and save the returned `secret`. This is the only response that contains it. ```bash curl -X POST https://webhooks.twilio.com/v1/Webhooks/SharedKeys \ -H 'Content-Type: application/json' \ -u {API_KEY_SID}:{API_KEY_SECRET} \ -d '{ "friendlyName": "Primary signing key" }' ``` 2. Create a Setting that signs with that key. `auth` is required, so use `NONE` if you don't want Twilio to authenticate itself to your endpoint. ```bash curl -X POST https://webhooks.twilio.com/v1/Webhooks/Settings \ -H 'Content-Type: application/json' \ -u {API_KEY_SID}:{API_KEY_SECRET} \ -d '{ "friendlyName": "Signed webhooks", "auth": { "source": "INLINE", "value": { "scheme": "NONE" } }, "signature": { "type": "SHARED_KEY", "sharedKeyId": "{SHARED_KEY_ID}", "algorithm": "HMAC_SHA256" } }' ``` 3. Test the Setting against your endpoint before any live traffic uses it. ```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://example.com/webhooks", "settingId": "{SETTING_ID}", "method": "POST" }' ``` 4. Create a default Rule so the Setting applies to every webhook. This returns `202 Accepted`. ```bash curl -X POST https://webhooks.twilio.com/v1/Webhooks/Rules \ -H 'Content-Type: application/json' \ -u {API_KEY_SID}:{API_KEY_SECRET} \ -d '{ "matchType": "DEFAULT", "settings": [ { "settingId": "{SETTING_ID}", "percentage": 100 } ] }' ``` 5. Poll the `Operation-Id` from the previous response until its status is `COMPLETED`. ```bash curl -X GET https://webhooks.twilio.com/v1/Webhooks/Operations/{OPERATION_ID} \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` ## Resources are immutable Settings, AuthProfiles, and SharedKeys accept changes only to `friendlyName` and, where present, `description`. To change any part of a configuration, create a new resource and point your Rule at it. Nothing you already deployed changes underneath you, and you roll forward or back by editing one Rule. Rules are the exception: you can change a Rule's match pattern and its Settings in place. ## Changes take 30 to 60 seconds to take effect Every write is saved immediately. Taking effect is a separate step: the change has to propagate to the plane that delivers your webhooks, and that takes **30 to 60 seconds for every resource type**. * **Rules** return `202 Accepted` with an `Operation-Id` header. Poll that [Operation][operations] to see when the change is live. * **Settings, AuthProfiles, and SharedKeys** return `201` or `200` and create no Operation, so there's nothing to poll. Allow the same window before relying on them. During propagation, webhooks may still use the previous configuration, and a Setting you just created isn't ready to [test][testing] yet. ## Account limits Each account can hold up to **50** of each resource type: SharedKeys, AuthProfiles, Settings, and Rules. Exceeding a limit returns [error 59200][59200]. To request an increase, contact [Twilio Support][support]. Only one `DEFAULT` Rule is allowed per account. ## Pagination List endpoints accept `pageSize` (default `50`, maximum `1000`) and `pageToken`. Each response carries a `meta` object with `nextToken` and `previousToken` when more pages exist. ```bash curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Settings?pageSize=100' \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` ## What's next? * [Configure webhook settings][settings], to define authentication, signing, connection, and edge zones * [Test webhook delivery][testing], to validate a Setting against your endpoint * [Configure webhook rules][rules], to apply a Setting to your webhooks * [Track webhook rule changes][operations], to confirm a rule change went live * [Configuration API FAQs][faq] [59200]: /docs/api/errors/59200 [api-keys]: /docs/iam/api-keys [auth]: /docs/usage/webhooks/webhook-auth-profiles [basic-auth]: /docs/glossary/what-is-basic-authentication [keys]: /docs/usage/webhooks/webhook-shared-keys [operations]: /docs/usage/webhooks/webhook-operations [rules]: /docs/usage/webhooks/webhook-rules [settings]: /docs/usage/webhooks/webhook-settings [support]: https://www.twilio.com/help/contact [testing]: /docs/usage/webhooks/webhook-testing [zones]: /docs/usage/webhooks/webhook-edge-zones [faq]: /docs/usage/webhooks/webhook-configuration-faq