The Prelude Session API uses webhooks to notify you when certain events occur.

​
How to setup your Webhook

1

Implement the handler

Develop a webhook endpoint to receive event data POST requests and GET verification requests.

2

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.

3

Activate the webhook

Activate the webhook using the POST /v2/session/apps/{appID}/webhooks/{webhookID}/activate endpoint.

4

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.

5

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.

​
app_id
string
required

An application's unique identifier.

Example:

"54e9ujn"

​
events
object[]
required