Authenticate webhooks with OAuth 2.0, Basic, or Digest

Twilio stores credentials in a required Webhook Setting auth object in one of two forms.

The standalone resource AuthProfile stores one set of credentials. To access these settings, get the authProfileId.

To fetch an access token from your authorization server, Twilio uses the client credentials flow. Twilio then sends the token as a Bearer token in the Authorization header of each webhook. When a token nears expiry, Twilio requests a replacement.

An OAuth 2.0 authorization server with client credentials support, and from it:

• The token endpoint URL
• A client ID
• A client secret
• Optionally, a scope
• Optionally, an audience

Make a POST request to the AuthProfiles resource.

1
curl -X POST https://webhooks.twilio.com/v1/Webhooks/AuthProfiles \
2
     -H 'Content-Type: application/json' \
3
     -u {API_KEY_SID}:{API_KEY_SECRET} \
4
     -d '{
5
           "type": "OAUTH2",
6
           "friendlyName": "Example authorization server",
7
           "tokenUrl": "https://auth.example.com/oauth2/token",
8
           "clientId": "{CLIENT_ID}",
9
           "clientSecret": "{CLIENT_SECRET}",
10
           "scope": "webhooks:write",
11
           "clientCredentialsAuthMethod": "CLIENT_SECRET_POST"
12
         }'

Returns 201 Created.

Save the returned id. Reference it from a Setting's auth object, then apply that Setting with a Webhook Rule.

With CLIENT_SECRET_POST, Twilio puts the credentials in the form body.

1
curl -X POST https://auth.example.com/oauth2/token \
2
     -H "Content-Type: application/x-www-form-urlencoded" \
3
     -d "grant_type=client_credentials" \
4
     -d "client_id={CLIENT_ID}" \
5
     -d "client_secret={CLIENT_SECRET}"

If you set a scope or an audience, Twilio includes them.

1
curl -X POST https://auth.example.com/oauth2/token \
2
     -H "Content-Type: application/x-www-form-urlencoded" \
3
     -d "grant_type=client_credentials" \
4
     -d "client_id={CLIENT_ID}" \
5
     -d "client_secret={CLIENT_SECRET}" \
6
     -d "scope=webhooks:write" \
7
     -d "audience=https://api.example.com"

With CLIENT_SECRET_BASIC, Twilio sends the client ID and secret in an Authorization: Basic header instead of the body.

A JSON body containing at least access_token, token_type, and expires_in. The token type must be Bearer, and expires_in must be at least 300 seconds.

1
{
2
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
3
  "token_type": "Bearer",
4
  "expires_in": 3600
5
}

If Twilio can't exchange your credentials for a token, it retries twice, 250 milliseconds apart. If those also 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.

Common causes are an unreachable authorization server, rotated or removed credentials, and a token issued with a type other than Bearer.

To use HTTP Digest, include the same username and password fields as Basic but set "type": "DIGEST".

1
curl -X POST https://webhooks.twilio.com/v1/Webhooks/AuthProfiles \
2
     -H 'Content-Type: application/json' \
3
     -u {API_KEY_SID}:{API_KEY_SECRET} \
4
     -d '{
5
           "type": "DIGEST",
6
           "friendlyName": "Legacy endpoint",
7
           "username": "{USERNAME}",
8
           "password": "{PASSWORD}"
9
         }'

Every setting requires the auth parameter. When Twilio shouldn't authenticate itself, set the scheme to NONE.

{ "auth": { "source": "INLINE", "value": { "scheme": "NONE" } } }

Never include Secrets.

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

Only friendlyName is editable.

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

To change tokenUrl, clientId, clientSecret, or any other credential field, create a different AuthProfile and point your Settings to the created AuthProfile.

To delete one AuthProfile, make a DELETE request of the AuthProfiles resource with its ID.

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

A successful request returns 204 No Content. A failed request returns 409 Conflict as a Setting still references it. To resolve the error, find the dependent Settings, then change where they point or delete them.

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

You can't change anything in an AuthProfile except its friendlyName. To rotate credentials, replace the resource.

1. Create a AuthProfile with the updated credentials.
2. Create a Setting that references the AuthProfile.
3. Test the added Setting against your endpoint.
4. Shift your Rule onto the added Setting. If you want to validate on live traffic first, make the shift gradually.
5. Delete the old Setting.
6. Delete the old AuthProfile.

• Sign webhooks with shared keys, to sign requests as well as authenticate them
• Configure webhook settings, to reference these credentials from a Setting
• Test webhook delivery, to check the credentials against your endpoint
• Configure webhook rules, to apply that Setting to your webhooks
• Configuration API FAQs