Webhook OAuth Authentication

Description

By default, Persona authenticates outbound webhooks with a shared secret and a Persona-Signature header. When OAuth is enabled, Persona additionally fetches an OAuth 2.0 access token from your authorization server using the Client Credentials grant (RFC 6749 §4.4) and attaches it as Authorization: Bearer <access_token> on every webhook delivery to your endpoint.

This is useful when your endpoint sits behind an identity-aware proxy, an API gateway, or a service mesh — or when your security policy requires every inbound request to carry a short-lived bearer token.

Before you begin

You’ll need the following from the authorization server you want Persona to authenticate against:

• A token endpoint URL. Must be publicly reachable over HTTPS.
• A client ID and client secret issued for Persona. We recommend creating a dedicated machine-to-machine client so you can revoke access without affecting other integrations.
• The token endpoint authentication method the client is configured for — either client_secret_basic (HTTP Basic Authorization header on the token request, the default for Okta, Auth0, and Apigee) or client_secret_post (credentials in the request body, NOT RECOMMENDED).
• Any scopes your endpoint expects, space-separated.

Configure OAuth on a Webhook

In the Dashboard, go to Integration → Webhooks and select an existing Webhook or click Add webhook. At the bottom of the form, expand the Advanced configuration section.

Check OAuth Enabled and fill in the following fields:

• Token URL (required) — HTTPS endpoint that issues access tokens. Must be publicly reachable.
• Token Endpoint Authentication (required) — how Persona presents the client credentials: client_secret_basic (HTTP Basic Authorization header) or client_secret_post (in the form body).
• Token Request Headers (optional) — additional static HTTP header key/values to include on the token request. The following headers are reserved: Authorization, Content-Type, Connection, Keep-Alive, Proxy-Connection, Transfer-Encoding, Te, Upgrade, Trailer, Host, Content-Length, Proxy-Authorization, Expect, X-Forwarded-For, X-Forwarded-Proto, Forwarded, Via.
• Client ID (required) — identifier for the OAuth client.
• Client Secret (required) — secret for the OAuth client.
• Scope (optional) — space-separated list of OAuth scopes per RFC 6749 §3.3 — for example, webhooks:write read.

Persona validates the configuration on save but does not call your token endpoint until the next event is delivered.

How delivery works

Token request

To retrieve an OAuth token, Persona POSTs to your token endpoint with grant_type=client_credentials. The exact request shape depends on the Token Endpoint Authentication you selected.

1
POST /oauth/token HTTP/1.1
2
Host: oauth.example.com
3
Authorization: Basic cGVyc29uYS1wcm9kOi4uLg==
4
Content-Type: application/x-www-form-urlencoded
5
6
grant_type=client_credentials&scope=webhooks%3Awrite

Persona expects a JSON response in the standard RFC 6749 §5.1 shape:

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

Webhook delivery

Once a token is available, Persona POSTs the event to your webhook endpoint with the token attached:

1
POST /your/webhook/path HTTP/1.1
2
Host: your-app.example.com
3
Authorization: Bearer eyJhbGciOi...
4
Content-Type: application/json
5
Persona-Signature: t=1714400000,v1=...
6
7
{ "data": { "type": "event", "...": "..." } }

The standard Persona-Signature HMAC header is still sent. We recommend you verify both — the OAuth token authenticates that Persona obtained valid credentials from your authorization server, and checking the signature confirms the payload was generated by Persona and has not been tampered with in transit.

Token request errors

If Persona cannot obtain an access token from your authorization server (For example, due to a network failure, a TLS error, a 10-second timeout, or a 4xx/5xx response from the token endpoint) the webhook delivery is recorded as failed and enters the standard retry schedule. Your endpoint is never called without a valid token.

The Webhook Event detail page in the Dashboard shows the underlying error class and HTTP status returned by your authorization server, so you can debug without needing logs from the auth server itself.

Limitations

• A Webhook may have at most one OAuth configuration. If you need to deliver the same events to two endpoints with different auth servers, configure two Webhooks.
• Token request headers are limited to 15 entries, 4 KB per header, 16 KB total. The Authorization, Content-Type, and Accept headers cannot be overridden.