--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/usage/webhooks/webhook-settings#article headline: Configure webhook settings description: Create Webhook Settings that define how Twilio authenticates, signs, and delivers your webhooks, then apply them with Webhook Rules. url: https://www.twilio.com/docs/usage/webhooks/webhook-settings inLanguage: en dateModified: 2026-09-07T13:32:03.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Configure webhook settings > \[!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 A Webhook Setting sets one complete delivery configuration, including: * how Twilio authenticates itself to your endpoint. * how Twilio signs the request. * what the connection timeouts and retries Twilio uses. * Which edge zones Twilio uses to deliver responses. A Setting takes effect only when a [Webhook Rule][rules] points a matching webhook URL at it. ## Setting properties | Property | Type | Necessity | Description | | -------------------- | ------ | --------- | ----------------------------------------------------------------------------- | | `id` | string | read-only | The Setting's identifier, in the form `webhooks_setting_` plus 26 characters. | | `type` | enum | read-only | `SYSTEM` for Settings Twilio manages, or `CUSTOMER` for Settings you create. | | `friendlyName` | string | optional | A name to identify the Setting. Up to 255 characters. Defaults to blank. | | `description` | string | optional | What the Setting is for. Up to 1024 characters. | | [`auth`][auth] | object | required | How Twilio authenticates itself to your endpoint. | | [`signature`][sig] | object | optional | How Twilio signs the request. | | [`connection`][conn] | object | optional | Timeouts and retry behavior. Twilio applies defaults when omitted. | | [`edgeZones`][zones] | object | optional | Which edge zones Twilio delivers from. All zones are eligible when omitted. | | `createdAt` | string | read-only | When the Setting was created, as an ISO 8601 timestamp. | | `updatedAt` | string | read-only | When the Setting last changed, as an ISO 8601 timestamp. | > \[!NOTE] > > Twilio creates `SYSTEM` Settings to simplify onboarding. You can read them and point Rules at them, but `PATCH` and `DELETE` return `409 Conflict`. ### Authentication `auth` is **required** on every Setting. It takes one of two shapes, selected by `source`. #### Inline credentials To embed the credentials in the Setting, use `"source": "INLINE"`. Twilio recommends inline for most cases. To set the authentication type, set `value.scheme` to `OAUTH2`, `BASIC`, `DIGEST`, or `NONE`. ```json title="OAuth 2.0, inline" { "auth": { "source": "INLINE", "value": { "scheme": "OAUTH2", "tokenUrl": "https://auth.example.com/oauth2/token", "clientId": "{CLIENT_ID}", "clientSecret": "{CLIENT_SECRET}", "scope": "webhooks:write", "clientCredentialsAuthMethod": "CLIENT_SECRET_POST" } } } ``` ```json title="No authentication" { "auth": { "source": "INLINE", "value": { "scheme": "NONE" } } } ``` To state explicitly that Twilio shouldn't authenticate itself, set `"scheme": "NONE"` as the `auth` object is required. #### Referenced credentials To share credentials across multiple Settings, use `"source": "REFERENCE"`. This points to an [AuthProfile][auth]. The AuthProfile determines the scheme. ```json title="Referencing an AuthProfile" { "auth": { "source": "REFERENCE", "authProfileId": "webhooks_sharedauth_01j9x8k2m4n6p8r0s2t4v6w8y0" } } ``` If you point to a non-existent or non-associated AuthProfile, Twilio returns [error 59201][59201]. ### Signature `signature` is optional and selects how Twilio signs the request, by `type`. | `type` | Fields | Notes | | -------------------- | -------------------------- | ----------------------------------------------------- | | `SHARED_KEY` | `sharedKeyId`, `algorithm` | Signs with a [SharedKey][keys] you manage. Preferred. | | `ACCOUNT_AUTH_TOKEN` | `algorithm` | Signs with your account authentication token. Legacy. | | `NONE` | — | Twilio doesn't sign the request. | `algorithm` is required for `SHARED_KEY` and `ACCOUNT_AUTH_TOKEN`, accepts `HMAC_SHA1` or `HMAC_SHA256`, and **can't be changed after you create the Setting**. ```json title="Signing with a shared key" { "signature": { "type": "SHARED_KEY", "sharedKeyId": "webhooks_sharedkey_01j9x8k2m4n6p8r0s2t4v6w8y0", "algorithm": "HMAC_SHA256" } } ``` > \[!NOTE] > > `ACCOUNT_AUTH_TOKEN` ties signing to your master account credential. `SHARED_KEY` isolates it and lets you rotate signing keys without touching account credentials. ### Connection `connection` sets how long Twilio waits and whether it retries. Twilio applies system defaults when you omit it. | Property | Necessity | Accepted values | Description | | ------------------ | --------- | ---------------- | ------------------------------------------------------ | | `connectTimeoutMs` | required | `100` to `15000` | How long Twilio waits to establish the TCP connection. | | `readTimeoutMs` | required | `100` to `15000` | How long Twilio waits for the response. | | `totalTimeoutMs` | optional | `100` to `60000` | Total time allowed including retries. | | `retryPolicy` | optional | object | Retry behavior. No retries when omitted. | `retryPolicy` takes `retryCount` (`0` to `5`, default `0`) and `retryOn`, an array of `HTTP_4XX`, `HTTP_5XX`, `CONNECTION_TIMEOUT`, `READ_TIMEOUT`, or `ALL`. ```json title="Connection settings with retries" { "connection": { "connectTimeoutMs": 5000, "readTimeoutMs": 10000, "totalTimeoutMs": 30000, "retryPolicy": { "retryCount": 3, "retryOn": ["HTTP_5XX", "CONNECTION_TIMEOUT", "READ_TIMEOUT"] } } } ``` > \[!WARNING] > > Twilio imposes a hard 15-second upper timeout on all call-related HTTP requests. That limit overrides a longer `totalTimeoutMs` on call-processing requests. Setting `connection` on a Setting isn't the same as a [URL connection override][overrides], the `#ct=…` fragment you append to a webhook URL. When a Rule applies a Setting to a webhook, that Setting takes precedence over any URL override on the same request. ### Edge zones The `edgeZones` property restricts the [edge zones][zones] from which Twilio can deliver a response. Without this property, Twilio can use all zones. ```json title="Preferring European zones" { "edgeZones": { "zones": ["eu-west", "eu-central"], "allowZoneFallback": false } } ``` ## Manage webhook settings To manage Settings, make HTTP requests to the Settings resource. ### Create a setting To create a Setting, make a `POST` request to the Settings resource. ```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": "Production webhooks", "description": "OAuth 2.0 plus shared key signing for api.example.com", "auth": { "source": "REFERENCE", "authProfileId": "{AUTH_PROFILE_ID}" }, "signature": { "type": "SHARED_KEY", "sharedKeyId": "{SHARED_KEY_ID}", "algorithm": "HMAC_SHA256" }, "connection": { "connectTimeoutMs": 5000, "readTimeoutMs": 10000 } }' ``` If successful, this request returns `201 Created`. ### List all settings To list all Settings in an account, make a `GET` request to the Settings resource. To filter Settings by the credentials or key a Setting uses, add the `authProfileId` or `sharedKeyId` query parameter. ```bash curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Settings?authProfileId={AUTH_PROFILE_ID}' \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` ### Fetch one setting To return one Setting from an account, make a `GET` request to the Settings resource. ```bash curl -X GET https://webhooks.twilio.com/v1/Webhooks/Settings/{SETTING_ID} \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` This request doesn't return `clientSecret`, `password`, or a SharedKey's `secret`. ### Update a setting name or description To update the `friendlyName` and `description` properties of one Setting, make a `PUT` request to the Settings resource. ```bash curl -X PATCH https://webhooks.twilio.com/v1/Webhooks/Settings/{SETTING_ID} \ -H 'Content-Type: application/json' \ -u {API_KEY_SID}:{API_KEY_SECRET} \ -d '{ "friendlyName": "Production webhooks (EU)" }' ``` To change `auth`, `signature`, `connection`, or `edgeZones`, create another Setting and update your Rule to point at it. ### Delete one setting To remove one Setting from an account, make a `DELETE` request to the Settings resource. ```bash curl -X DELETE https://webhooks.twilio.com/v1/Webhooks/Settings/{SETTING_ID} \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` * If successful, this request returns `204 No Content`. * If a Rule still references the Setting or the Setting is `SYSTEM`, this request returns `409 Conflict`. To resolve a conflict: 1. Find the dependent Rules. ```bash curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Rules?settingId={SETTING_ID}' \ -u {API_KEY_SID}:{API_KEY_SECRET} ``` 2. Repoint or delete them. ## Replace a setting with no downtime Because Settings are immutable, changing a configuration means swapping which Setting a Rule points at. 1. Create the replacement Setting with the new configuration. 2. [Test][testing] it against your endpoint. 3. `PATCH` your Rule so its `settings` array names the new Setting at `100` percent. To validate on a slice of live traffic first, split the array across both Settings. See [Shift traffic between settings][rules-traffic]. 4. Wait for the Rule's [Operation][operations] to reach `COMPLETED`. 5. Delete the old Setting. ## What's next? * [Test webhook delivery][testing], to validate the Setting before live traffic uses it * [Configure webhook rules][rules], to apply the Setting to your webhooks * [Choose webhook edge zones][zones], to restrict where webhooks egress from * [Configuration API FAQs][faq] [59201]: /docs/api/errors/59201 [auth]: /docs/usage/webhooks/webhook-auth-profiles [conn]: #connection [keys]: /docs/usage/webhooks/webhook-shared-keys [operations]: /docs/usage/webhooks/webhook-operations [overrides]: /docs/usage/webhooks/webhooks-connection-overrides [rules]: /docs/usage/webhooks/webhook-rules [rules-traffic]: /docs/usage/webhooks/webhook-rules#shift-traffic-between-settings [sig]: #signature [testing]: /docs/usage/webhooks/webhook-testing [zones]: /docs/usage/webhooks/webhook-edge-zones [faq]: /docs/usage/webhooks/webhook-configuration-faq