--- "@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-09-07T13:32:03.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Webhooks configuration API FAQs > \[!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 ## 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 happens if I don't create any rule? Twilio sends the webhook with no Setting applied. Twilio doesn't authenticate itself to your endpoint, and it uses default connection behavior. Signing falls back to the default: your account authentication token with the `HMAC_SHA1` algorithm, exactly as it worked before you used the configuration API. ## 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, so a test run within 30 to 60 seconds of creating the Setting can return `422`. Wait for the window to pass and retry. ```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" }' ``` ## 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 with a Rule. 1. Create a new Setting with the new configuration and test it. 2. `PATCH` the Rule so its `settings` array splits traffic, for example 90 percent to the old Setting and 10 to the new one. The percentages must sum to 100. 3. Wait for the [Operation][operations] to complete, then check your endpoint. 4. Repeat with a larger share, then move fully to the new Setting. 5. Delete the old Setting. A Rule holds at most two Settings, so stage one change at a time. See [Shift traffic between settings][rules-traffic]. ## Why did my rule change not take effect immediately? Saving and taking effect are separate steps. The write itself is immediate — the API persists it and responds straight away. Propagating that change to the plane that delivers your webhooks takes 30 to 60 seconds, and that applies to every resource type, not only Rules. Rule writes return `202 Accepted` with an `Operation-Id` header, so poll that [Operation][operations] until its status is `COMPLETED`. Settings, AuthProfiles, and SharedKeys create no Operation — allow the same 30 to 60 seconds before relying on them. ## 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-Signature-Key-Sid` 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 yourself to isolate the cause. See [Authenticate webhooks with OAuth 2.0][auth]. ## 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. ## Why can't I use Basic authentication on my default rule? A default Rule matches every otherwise-unmatched webhook URL, so Basic credentials on it would be sent to every destination Twilio calls. Twilio rejects that configuration with [error 59202][59202]. Scope Basic authentication to an exact-match or prefix-match Rule, or use OAuth 2.0 or Digest on the default Rule. ## Why can't I delete a setting, AuthProfile, or shared key? Something still references it, and the API returns `409 Conflict` 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 takes precedence over a URL override on that request. ## I onboarded to the private beta. Does my integration still work? Yes. The private beta API at `https://preview.twilio.com/Webhooks` remains available to accounts already using it. It's a different API from `https://webhooks.twilio.com/v1/Webhooks`, with different resources, field names, and identifier formats, so code written against one doesn't work against the other. To move over, rebuild your configuration against the public beta API using these pages, then retire the old one. [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 [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 [settings]: /docs/usage/webhooks/webhook-settings [support]: https://www.twilio.com/help/contact [testing]: /docs/usage/webhooks/webhook-testing [webhook-security]: /docs/usage/webhooks/webhooks-security