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.

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.

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 until they returnCOMPLETED.
• 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.

Yes, existing webhook URLs keep working until you create a rule that covers them. A webhook that no rule matches behaves as it did before this API existed. Twilio authenticates with credentials in the URL, applies connection 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.

To migrate to the configuration API, 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.

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

Settings are immutable, so you create a replacement and shift traffic onto it by PATCHing 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.

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 at 100 percent instead, which keeps the URL under the API while restoring its old behavior.

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

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-Webhooks-Signature-Settings 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 with the curl commands under What Twilio sends to your authorization server.

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.

No. OAuth 1 isn't compatible with OAuth 2.0.

Accounts with Twilio Editions reach your authorization server through static proxy addresses.

Twilio rejects that with error 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.

Something still references it, and the API returns 409 Conflict with error 59100 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 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 is the exception: it applies the URL overrides rather than ignoring them.

Twilio renamed the signature header and changed its value format.

If your endpoint reads the old header to choose a validation secret, update it to read X-Twilio-Webhooks-Signature-Settings.

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.