> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prelude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn about the webhooks used by Prelude Auth.

Prelude Auth uses webhooks to notify you when certain events occur.

## How to setup your Webhook

<Steps>
  <Step title="Implement the handler">
    Develop a webhook endpoint to receive event data POST requests and GET verification requests.
  </Step>

  <Step title="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`](/auth/api-reference/management/webhooks/create-webhook) endpoint.
  </Step>

  <Step title="Activate the webhook">
    Activate the webhook using the [`POST /v2/session/apps/{appID}/webhooks/{webhookID}/activate`](/auth/api-reference/management/webhooks/activate-webhook) endpoint.
  </Step>

  <Step title="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](/auth/documentation/webhooks/verification-event) page.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/auth/documentation/jwks) 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.

The signature uses the same RSASSA-PSS parameters as the Verify and Notify webhooks (SHA-256, MGF1-SHA-256, maximum salt length, signed over the raw request body bytes). See the [Verify webhook signature reference](/verify/v2/documentation/webhook#webhook-signature) for the full parameter table and reference implementations — the only difference is that the public key comes from the JWKS endpoint above instead of the dashboard.

<Warning>
  Prelude signs with the *maximum* PSS salt length, not a fixed 32 bytes. Most libraries auto-detect the salt length when verifying; libraries that require an explicit value (e.g. Java, .NET) should compute it from the key rather than hardcoding it.
</Warning>

## 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`
* `user.passkey.registered`
* `user.passkey.deleted`
* `user.passkey.assertion_failed`
* `migration.hook_failed`
* `step_up.hook_failed`

## 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
```