Configure webhook settings

auth is required on every Setting. It takes one of two shapes, selected by source.

To embed the credentials in the Setting, use "source": "INLINE". Twilio recommends inline for most cases.

To set the authentication type, set value.scheme to OAUTH2, BASIC, DIGEST, or NONE.

1
{
2
  "auth": { "source": "INLINE", "value": { "scheme": "NONE" } }
3
}

To state explicitly that Twilio shouldn't authenticate itself, set "scheme": "NONE" as the auth object is required.

To share credentials across multiple Settings, use "source": "REFERENCE". This points to an AuthProfile. The AuthProfile determines the scheme.

1
{
2
  "auth": {
3
    "source": "REFERENCE",
4
    "authProfileId": "webhooks_sharedauth_01j9x8k2m4n6p8r0s2t4v6w8y0"
5
  }
6
}

If you point to a non-existent or non-associated AuthProfile, Twilio returns error 59201.

signature is optional and selects how Twilio signs the request, by type.

algorithm is required for SHARED_KEY and ACCOUNT_AUTH_TOKEN, accepts HMAC_SHA1 or HMAC_SHA256, and can't be changed after you create the Setting.

connection sets how long Twilio waits and whether it retries. Twilio applies system defaults when you omit it.

retryPolicy takes retryCount (0 to 5, default 0) and retryOn, an array of HTTP_4XX, HTTP_5XX, CONNECTION_TIMEOUT, READ_TIMEOUT, or ALL.

1
{
2
  "connection": {
3
    "connectTimeoutMs": 5000,
4
    "readTimeoutMs": 10000,
5
    "totalTimeoutMs": 30000,
6
    "retryPolicy": {
7
      "retryCount": 3,
8
      "retryOn": ["HTTP_5XX", "CONNECTION_TIMEOUT", "READ_TIMEOUT"]
9
    }
10
  }
11
}

Setting connection on a Setting isn't the same as a URL connection override, the #ct=… fragment you append to a webhook URL. When a Rule applies a Setting to a webhook, that Setting takes precedence over any URL override on the same request.

The edgeZones property restricts the edge zones from which Twilio can deliver a response. Without this property, Twilio can use all zones.

Every account has one Setting with type set to SYSTEM. It reproduces the behavior Twilio applied before this API existed, reading HTTP credentials and connection overrides from the webhook URL.

Point a Rule at it to bring a URL under the configuration API without changing how Twilio delivers its webhooks. That makes it the starting point for migrating an endpoint: you can prove the Rule works before you change any behavior.

Fetch it by filtering on type rather than hardcoding its ID.

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

PATCH and DELETE on the system Setting return 409 Conflict.

To manage Settings, make HTTP requests to the Settings resource.

To create a Setting, make a POST request to the Settings resource.

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": "Production webhooks",
6
           "description": "OAuth 2.0 plus shared key signing for api.example.com",
7
           "auth": {
8
             "source": "REFERENCE",
9
             "authProfileId": "{AUTH_PROFILE_ID}"
10
           },
11
           "signature": {
12
             "type": "SHARED_KEY",
13
             "sharedKeyId": "{SHARED_KEY_ID}",
14
             "algorithm": "HMAC_SHA256"
15
           },
16
           "connection": {
17
             "connectTimeoutMs": 5000,
18
             "readTimeoutMs": 10000
19
           }
20
         }'

If successful, this request returns 201 Created.

To list all Settings in an account, make a GET request to the Settings resource. To filter Settings by the credentials or key a Setting uses, add the authProfileId or sharedKeyId query parameter. Add type with SYSTEM or CUSTOMER to filter by kind.

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

To return one Setting from an account, make a GET request to the Settings resource.

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

This request doesn't return clientSecret, password, or a SharedKey's secret.

To update the friendlyName and description properties of one Setting, make a PUT request to the Settings resource.

1
curl -X PATCH https://webhooks.twilio.com/v1/Webhooks/Settings/{SETTING_ID} \
2
     -H 'Content-Type: application/json' \
3
     -u {API_KEY_SID}:{API_KEY_SECRET} \
4
     -d '{ "friendlyName": "Production webhooks (EU)" }'

To change auth, signature, connection, or edgeZones, create another Setting and update your Rule to point at it.

To remove one Setting from an account, make a DELETE request to the Settings resource.

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

• If successful, this request returns 204 No Content.
• If a Rule still references the Setting or the Setting is SYSTEM, this request returns 409 Conflict. To resolve a conflict:
  1. Find the dependent Rules.
     Copy code block

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

  2. Repoint or delete them.

Because Settings are immutable, changing a configuration means swapping which Setting a Rule points at.

1. Create the replacement Setting with the new configuration.
2. Test it against your endpoint.
3. PATCH your Rule so its settings array names the new Setting at 100 percent. To validate on a slice of live traffic first, split the array across both Settings. See Shift traffic between settings.
4. Wait for the Rule's Operation to reach COMPLETED.
5. Delete the old Setting.

• Test webhook delivery, to validate the Setting before live traffic uses it
• Configure webhook rules, to apply the Setting to your webhooks
• Choose webhook edge zones, to restrict where webhooks egress from
• Configuration API FAQs