Skip to main content
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.Timeout: Prelude will wait up to 10 seconds for your endpoint to respond. If your endpoint doesn’t respond within this timeframe or returns a non-200 status code, the request will be considered failed.Retries: Failed requests will be retried with exponential backoff for up to 2 weeks. Retries are spaced progressively further apart (1 min, 2 min, 4 min, … up to 12 hours) to allow your endpoint time to recover if it’s temporarily down.

​
Webhook signature

To ensure the authenticity of the webhook events, we use a signature mechanism. The signature is a base64 URL-encoded RSASSA-PSS on the 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 rsassa-pss-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. You can then verify the signature of the webhook events in your webhook endpoint and process the event only if the signature is valid.

​
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.

​
IP Whitelisting

You should whitelist the following IP addresses to ensure that your webhook endpoint receives events from Prelude: 
34.252.67.209
52.30.192.161
34.248.153.151
​
app_id
string
required

An application's unique identifier.

Examples:

"54e9ujn"

"fvua38g"

​
events
object[]
required