Webhook OAuth Authentication
Authenticate outbound webhook deliveries with OAuth 2.0 client credentials
This feature is restricted to customers on the Enterprise plan. Please reach out to your Account Team or contact us if you are interested in enabling and setting up this feature.
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.
Persona supports the Client Credentials grant only. Authorization Code, PKCE, Device Code, and JWT-based client authentication (private_key_jwt, client_secret_jwt) are not currently available.
You’ll need the following from the authorization server you want Persona to authenticate against:
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).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:
client_secret_basic (HTTP Basic Authorization header) or client_secret_post (in the form body).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.webhooks:write read.
Persona validates the configuration on save but does not call your token endpoint until the next event is delivered.
When you save the form, your Client ID and Client Secret are encrypted at rest and never returned to the Dashboard. If you re-open the Webhook later, these fields display with a Leave blank to keep existing value placeholder. Leave them blank to keep the existing values, or enter new values to replace them.
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.
Persona expects a JSON response in the standard RFC 6749 §5.1 shape:
Once a token is available, Persona POSTs the event to your webhook endpoint with the token attached:
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.
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.
For security, the Authorization header value is redacted to <redacted> in the request payload Persona stores on each Webhook Event. The bearer token is never visible in the Dashboard, audit exports, or support tooling.
Authorization, Content-Type, and Accept headers cannot be overridden.