Webhooks configuration API

https://webhooks.twilio.com/v1/Webhooks

If you onboarded to the private beta, that API is at preview.twilio.com and remains available to your account. It's a separate API, so see I onboarded to the private beta before you migrate.

Every request uses HTTP basic authentication. Use an API key SID as the username and the API key secret as the password.

1
curl -X GET https://webhooks.twilio.com/v1/Webhooks/Settings \
2
     -u {API_KEY_SID}:{API_KEY_SECRET}

You can use your account SID and authentication token instead, but limit that to local testing.

Two resources do the main work, and the rest support them.

A Setting on its own changes nothing. Twilio applies a Setting only when a Rule points a matching webhook URL at it.

When Twilio sends a webhook, it compares the destination URL against your Rules, applies the Setting that the winning Rule names, and delivers the request using that Setting's authentication, signing, connection, and edge zone configuration.

If no Rule matches, Twilio sends the webhook with no Setting applied: Twilio doesn't authenticate itself to your endpoint, it signs the request with your account authentication token using HMAC_SHA1, and it uses default connection behavior.

This creates a configuration that signs every webhook from your account with a key you control.

1. Create a SharedKey and save the returned secret. This is the only response that contains it.

   Copy code block

   1
   curl -X POST https://webhooks.twilio.com/v1/Webhooks/SharedKeys \
   2
        -H 'Content-Type: application/json' \
   3
        -u {API_KEY_SID}:{API_KEY_SECRET} \
   4
        -d '{ "friendlyName": "Primary signing key" }'

2. Create a Setting that signs with that key. auth is required, so use NONE if you don't want Twilio to authenticate itself to your endpoint.

   Copy code block

   1
   curl -X POST https://webhooks.twilio.com/v1/Webhooks/Settings \
   2
        -H 'Content-Type: application/json' \
   3
        -u {API_KEY_SID}:{API_KEY_SECRET} \
   4
        -d '{
   5
              "friendlyName": "Signed webhooks",
   6
              "auth": { "source": "INLINE", "value": { "scheme": "NONE" } },
   7
              "signature": {
   8
                "type": "SHARED_KEY",
   9
                "sharedKeyId": "{SHARED_KEY_ID}",
   10
                "algorithm": "HMAC_SHA256"
   11
              }
   12
            }'

3. Test the Setting against your endpoint before any live traffic uses it.

   Copy code block

   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://example.com/webhooks",
   6
              "settingId": "{SETTING_ID}",
   7
              "method": "POST"
   8
            }'

4. Create a default Rule so the Setting applies to every webhook. This returns 202 Accepted.

   Copy code block

   1
   curl -X POST https://webhooks.twilio.com/v1/Webhooks/Rules \
   2
        -H 'Content-Type: application/json' \
   3
        -u {API_KEY_SID}:{API_KEY_SECRET} \
   4
        -d '{
   5
              "matchType": "DEFAULT",
   6
              "settings": [ { "settingId": "{SETTING_ID}", "percentage": 100 } ]
   7
            }'

5. Poll the Operation-Id from the previous response until its status is COMPLETED.

   Copy code block

   1
   curl -X GET https://webhooks.twilio.com/v1/Webhooks/Operations/{OPERATION_ID} \
   2
        -u {API_KEY_SID}:{API_KEY_SECRET}

Settings, AuthProfiles, and SharedKeys accept changes only to friendlyName and, where present, description. To change any part of a configuration, create a new resource and point your Rule at it. Nothing you already deployed changes underneath you, and you roll forward or back by editing one Rule.

Rules are the exception: you can change a Rule's match pattern and its Settings in place.

Every write is saved immediately. Taking effect is a separate step: the change has to propagate to the plane that delivers your webhooks, and that takes 30 to 60 seconds for every resource type.

• Rules return 202 Accepted with an Operation-Id header. Poll that Operation to see when the change is live.
• Settings, AuthProfiles, and SharedKeys return 201 or 200 and create no Operation, so there's nothing to poll. Allow the same window before relying on them.

During propagation, webhooks may still use the previous configuration, and a Setting you just created isn't ready to test yet.

Each account can hold up to 50 of each resource type: SharedKeys, AuthProfiles, Settings, and Rules. Exceeding a limit returns error 59200. To request an increase, contact Twilio Support.

Only one DEFAULT Rule is allowed per account.

List endpoints accept pageSize (default 50, maximum 1000) and pageToken. Each response carries a meta object with nextToken and previousToken when more pages exist.

1
curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Settings?pageSize=100' \
2
     -u {API_KEY_SID}:{API_KEY_SECRET}

• Configure webhook settings, to define authentication, signing, connection, and edge zones
• Test webhook delivery, to validate a Setting against your endpoint
• Configure webhook rules, to apply a Setting to your webhooks
• Track webhook rule changes, to confirm a rule change went live
• Configuration API FAQs