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