Webhooks
Learn about the webhooks used by the Session API.
The Prelude Session API uses webhooks to notify you when certain events occur.
How to setup your Webhook
Implement the handler
Develop a webhook endpoint to receive event data POST requests and GET verification requests.
Register the webhook
Register the webhook endpoint by setting the URL and the events you want to subscribe to, using the POST /v2/session/apps/{appID}/webhooks
endpoint.
Activate the webhook
Activate the webhook using the POST /v2/session/apps/{appID}/webhooks/{webhookID}/activate
endpoint.
Verify the webhook
Prelude’s webhook service will send a GET activation request to the webhook endpoint. Make sure to return a 200 OK
along with the challenge response to acknowledge receipt of the event. See more details in the Activation Challenge Request page.
Start receiving events
Start receiving events. For each request to your webhook, also validate the signature. Make sure to return a 200 OK
HTTP response to the POST request to acknowledge receipt of the event. If you don’t, Prelude will retry sending the event for 2 weeks.
Webhook signature
To ensure the authenticity of the webhook events, we use a signature mechanism.
The signature is a base64 encoded HMAC-SHA256 hash of the payload, using the your application’s access token signing secret as the key.
The signature is sent as a string prefixed with sha256=
in the X-Webhook-Signature
header of each request to your webhook endpoint.
You can get the public key to verify the signature from the JWKS endpoint of your application.
Webhook events
You can subscribe to the following events:
user.created
user.deleted
user.profile.updated
user.identifier.created
user.identifier.deleted
user.session.created
user.session.revoked
Webhook payload
Events are received in batches. Each batch contains a list of events and only contains events for the application that the webhook is registered to.