--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/usage/webhooks/webhook-configuration-faq#article headline: Webhooks configuration API FAQs description: Answers to common questions about configuring Twilio webhook authentication, signing, rules, and delivery behavior. url: https://www.twilio.com/docs/usage/webhooks/webhook-configuration-faq inLanguage: en dateModified: 2026-10-14T20:48:46.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Webhooks configuration API FAQs ## How does the configuration API decide what to apply? Before Twilio sends a webhook, it compares the destination URL against your [Webhook Rules][rules] in evaluation order: exact-match Rules longest first, then prefix-match Rules longest first, then the default Rule. Twilio applies the first Rule that matches, using the [Setting][settings] that Rule names. If the Rule's `settings` array holds two Settings, Twilio picks between them according to their percentages. ## What's the system Setting? The system setting is the one setting Twilio ships in every account. It reproduces legacy delivery, reading credentials and connection overrides from the webhook URL. A Rule pointing at the system setting changes nothing about how Twilio sends a webhook. You can't modify or delete this Setting. To learn more, see [system Setting][system]. ## Why doesn't my rule match? A Rule the API accepted might match no existing Rules. The `X-Twilio-Webhooks-Settings` header on a delivered webhook names the Rule that matched, and it's absent when no Rules did. If the `X-Twilio-Webhooks-Settings` is absent, use the following to troubleshoot the missing Rule: * **The change hasn't propagated**: A Rule takes 30 to 90 seconds to go live. Poll its [Operation][operations] until they return`COMPLETED`. * **Another Rule is more specific**: Twilio evaluates exact matches first, then the longest prefix, then the default Rule. * **The trailing slash is wrong**: A `prefix` must end with `/`; an exact `value` must not. * **The path case differs**: Paths are case-sensitive, so a Rule for `/hook` doesn't match a webhook sent to `/Hook`. * **The pattern isn't the URL Twilio calls**: Compare it against the webhook URL configured on the resource, not the one in your application code. Learn more about [how Twilio matches a rule pattern][rules]. ## Do my existing webhook URLs keep working? Yes, existing webhook URLs keep working until you create a rule that covers them. A webhook that no [rule][rules] matches behaves as it did before this API existed. Twilio authenticates with credentials in the URL, applies [connection overrides][overrides] in the URL fragment, and signs with your account authentication token using `HMAC_SHA1`. Adoption is based on each URL pattern, so you can move one endpoint over to the new URL and leave the rest alone. ## How do I migrate an existing endpoint? To [migrate to the configuration API][migrate], start by pointing a Rule at the system Setting, which keeps delivery unchanged, then shift traffic onto a Setting of your own a percentage at a time. ## Do I need a rule even if I only have one setting? Yes. A Setting never applies on its own. To apply one to every webhook, create a Rule with `matchType` set to `DEFAULT`. ## Can I use different credentials or keys for different webhook URLs? Yes, and that's what Rules are for. Create a Setting per configuration, then create a Rule per URL pattern pointing at the right Setting. Use `EXACT_MATCH` for a single endpoint and `PREFIX_MATCH` for a domain or path. ## How do I test a configuration before live traffic uses it? Use the [Tests endpoint][testing]. It sends one webhook to a URL you choose using the Setting you name, without a Rule and without affecting live traffic. A Setting has to finish propagating before it can be tested. A test run within 30 to 90 seconds of creating the Setting can return `422`. Wait for the 30-90 second window to pass and then retry. ## I want to change a setting. How do I deploy the change gradually? Settings are immutable, so you create a replacement and shift traffic onto it by `PATCH`ing the Rule's `settings` array. A Rule holds at most two Settings, so stage one change at a time. Learn more about the full sequence in [Shift traffic between settings][rules-traffic]. ## How do I undo a configuration? Delete the Rule. Its webhooks go to the next Rule that matches them, or to legacy delivery if no Rule does. If you're mid-migration, `PATCH` the Rule back to the [system Setting][system] at 100 percent instead, which keeps the URL under the API while restoring its old behavior. ## Why did my rule change not take effect immediately? Saving and taking effect are separate steps. The write is immediate, but it takes 30 to 90 seconds to reach the plane that delivers your webhooks. Rule writes return `202 Accepted` with an `Operation-Id` header, so poll that [Operation][operations] until its status is `COMPLETED`. Until it completes, webhooks may still use the previous configuration. See [Changes take 30 to 90 seconds to take effect][propagation]. ## Can I edit a setting, AuthProfile, or shared key? Only `friendlyName`, and `description` where the resource has one. Everything else is immutable. To change a configuration, create a new resource and point your Rule at it. That's what makes rollouts and rollbacks a single Rule edit. Rules are the exception: you can change a Rule's match pattern and its Settings in place. ## Does authentication replace signature validation? No. They answer different questions. A signature proves the request body wasn't altered in transit. [Authentication][auth] proves Twilio is allowed to call your endpoint. Keep [validating signatures][webhook-security], and always validate them if you serve webhooks over HTTP rather than HTTPS. ## Can I configure both authentication and signing on one setting? Yes. `auth` and `signature` are independent fields on the same Setting and work together. Twilio encourages configuring at least one, over HTTPS. ## Which secret signed a given webhook? Read the `X-Twilio-Webhooks-Signature-Settings` header. When it's present, the named [SharedKey][keys] signed the request. When it's absent, your account authentication token did. ## Can I retrieve a shared key's secret later? No. The `secret` is returned only in the response that creates the key and can't be recovered. If you lose it, create a new SharedKey and rotate onto it. ## Why is my OAuth 2.0 AuthProfile rejected when I create it? Twilio validates OAuth 2.0 credentials at creation by fetching a token from your authorization server. A `400` means that fetch failed. Check your authorization server's logs, then reproduce the token request with the `curl` commands under [What Twilio sends to your authorization server][sends]. ## What happens if my authorization server goes down? Twilio retries the token request twice, 250 milliseconds apart. If those fail, Twilio **drops the webhook** and logs [error 97001][97001] in the [Twilio Debugger][debugger]. Twilio tries again after 300 seconds, and webhooks matching that Setting may be dropped during that window. ## Can I use an OAuth 1 authorization server? No. OAuth 1 isn't compatible with OAuth 2.0. ## Do I need to allowlist any IP addresses? Accounts with [Twilio Editions][editions] reach your authorization server through static proxy addresses. ## Why can't I use Basic authentication on my default rule? Twilio rejects that with [error 59202][59202]: a default Rule matches every otherwise-unmatched URL, so your credentials would reach every destination Twilio calls. Scope Basic to an exact-match or prefix-match Rule, or use OAuth 2.0 or Digest. ## Why can't I delete a setting, AuthProfile, or shared key? Something still references it, and the API returns `409 Conflict` with [error 59100][59100] rather than breaking a live configuration. Find the dependents, repoint or delete them, then retry. | Deleting | Find dependents with | | -------------- | ---------------------------------------------- | | A Setting | `GET /v1/Webhooks/Rules?settingId={id}` | | An AuthProfile | `GET /v1/Webhooks/Settings?authProfileId={id}` | | A SharedKey | `GET /v1/Webhooks/Settings?sharedKeyId={id}` | A `409` on a Setting can also mean it's a `SYSTEM` Setting, which Twilio manages and you can't modify or delete. ## What are the account limits? Up to 50 each of SharedKeys, AuthProfiles, Settings, and Rules, plus one default Rule. Exceeding a limit returns [error 59200][59200]. To request an increase, contact [Twilio Support][support]. ## How do connection settings relate to URL connection overrides? They're separate mechanisms. A Setting's `connection` object configures timeouts and retries for every webhook the Setting applies to. A [URL connection override][overrides] is the `#ct=…` fragment appended to a single webhook URL. When a Rule applies a Setting to a webhook, the Setting replaces the URL overrides outright. Twilio ignores every key in the fragment, including keys the Setting leaves unset, which fall back to their defaults rather than to the URL value. Where no Rule matches, the URL overrides still apply. The [system Setting][system] is the exception: it applies the URL overrides rather than ignoring them. ## I used the public beta. What changed? Twilio renamed the signature header and changed its value format. | | Public beta | General availability | | ------ | ------------------------------------- | ----------------------------------------- | | Header | `X-Twilio-Webhook-Signature-Settings` | `X-Twilio-Webhooks-Signature-Settings` | | Value | `{shared_key_id};{algorithm}` | `key=,algorithm=` | If your endpoint reads the old header to choose a validation secret, update it to read `X-Twilio-Webhooks-Signature-Settings`. ## I onboarded to the private beta. Does my integration still work? Yes, and there's nothing to rebuild. Twilio migrated private beta accounts to this API, so your existing configuration is already here. The two APIs expose different resources, field names, and identifier formats, so code written against the private beta API won't work against this one. Point your integration at `https://webhooks.twilio.com/v1/Webhooks` and follow these pages. > \[!WARNING] > > Changes you make through this API don't appear in the private beta API. After you start using this API, any configuration you read or write through `preview.twilio.com` gives inconsistent results. [59100]: /docs/api/errors/59100 [59200]: /docs/api/errors/59200 [59202]: /docs/api/errors/59202 [97001]: /docs/api/errors/97001 [auth]: /docs/usage/webhooks/webhook-auth-profiles [debugger]: /docs/usage/troubleshooting/debugging-your-application [editions]: https://www.twilio.com/en-us/editions [sends]: /docs/usage/webhooks/webhook-auth-profiles#what-twilio-sends-to-your-authorization-server [keys]: /docs/usage/webhooks/webhook-shared-keys [operations]: /docs/usage/webhooks/webhook-operations [migrate]: /docs/usage/webhooks/webhook-migration [propagation]: /docs/usage/webhooks/webhook-configuration#changes-take-30-to-90-seconds-to-take-effect [overrides]: /docs/usage/webhooks/webhooks-connection-overrides [rules]: /docs/usage/webhooks/webhook-rules [rules-traffic]: /docs/usage/webhooks/webhook-rules#shift-traffic-between-settings [settings]: /docs/usage/webhooks/webhook-settings [system]: /docs/usage/webhooks/webhook-settings#the-system-setting [support]: https://www.twilio.com/help/contact [testing]: /docs/usage/webhooks/webhook-testing [webhook-security]: /docs/usage/webhooks/webhooks-security