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.

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.

No. A signature proves the request wasn't tampered with. 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. Twilio encourages configuring at least one, over HTTPS.

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

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

Twilio validates OAuth 2.0 credentials when you create the resource by fetching a token. 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.

• 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