Webhooks configuration API FAQs

Before Twilio sends a webhook, it compares the destination URL against your Webhook 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 that Rule names.

If the Rule's settings array holds two Settings, Twilio picks between them according to their percentages.

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.

Yes. A Setting never applies on its own. To apply one to every webhook, create a Rule with matchType set to DEFAULT.

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.

Use the Tests endpoint. 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.

1
curl -X POST https://webhooks.twilio.com/v1/Webhooks/Tests \
2
     -H 'Content-Type: application/json' \
3
     -u {API_KEY_SID}:{API_KEY_SECRET} \
4
     -d '{
5
           "url": "https://api.example.com/webhooks/test",
6
           "settingId": "{SETTING_ID}",
7
           "method": "POST"
8
         }'

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 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.

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 until its status is COMPLETED. Settings, AuthProfiles, and SharedKeys create no Operation — allow the same 30 to 60 seconds before relying on them.

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.

No. They answer different questions. A signature proves the request body wasn't altered in transit. Authentication proves Twilio is allowed to call your endpoint. Keep validating signatures, and always validate them if you serve webhooks over HTTP rather than HTTPS.

Yes. auth and signature are independent fields on the same Setting and work together. Twilio encourages configuring at least one, over HTTPS.

Read the X-Twilio-Signature-Key-Sid header. When it's present, the named SharedKey signed the request. When it's absent, your account authentication token did.

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.

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.

Twilio retries the token request twice, 250 milliseconds apart. If those fail, Twilio drops the webhook and logs error 97001 in the Twilio Debugger. Twilio tries again after 300 seconds, and webhooks matching that Setting may be dropped during that window.

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. Scope Basic authentication to an exact-match or prefix-match Rule, or use OAuth 2.0 or Digest on the default Rule.

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.

A 409 on a Setting can also mean it's a SYSTEM Setting, which Twilio manages and you can't modify or delete.

Up to 50 each of SharedKeys, AuthProfiles, Settings, and Rules, plus one default Rule. Exceeding a limit returns error 59200. To request an increase, contact Twilio Support.

They're separate mechanisms. A Setting's connection object configures timeouts and retries for every webhook the Setting applies to. A URL connection override 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.

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.