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

# Webhook

> Learn how to easily register a webhook with Prelude to get notified when your messages are delivered and billed.

<Warning>
  The V1 API is **deprecated**. Starting November 1st 2025, no support will be provided for the V1 API and it will be **removed by April 2026**. No new features nor functionality will be added to the V1 API. Please use the [V2 Verify API](/verify/v2/documentation/introduction) instead. For more information refer to the [V2 Migration Guide](/verify/v2/documentation/v2-migration-guide).
</Warning>

## Why use the webhook?

When integrating Prelude, you might want your system to receive events as they occur in your Prelude apps,
so that your backend systems can execute actions accordingly.

To register a webhook, you need to provide a `callback_url` along with your [Authentication](/verify/v1/api-reference/send-a-code) request.
After registration, Prelude can push real-time event data to your webhook endpoint when events happen in your app.

## The event object

There are three types of events that can be sent to your webhook endpoint:

* **Authentication** events: sent when an Authentication is created.
* **Attempt** events: sent when a message is sent to the user.
* **Delivery status** events: sent when we receive a delivery status from the carrier.

<CodeGroup>
  ```json Authentication event theme={null}
  {
    "id": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
    "auth_uuid": "f54b6bcc-3638-4437-83c8-1f76631c9403",
    "type": "authentication",
    "recipient_phone_number": "+33xxxxxxxx",
    "price": {
      "amount": 0.009,
      "currency": "EUR"
    },
    "time": "2023-05-09T12:09:31+0000",
    "correlation_id": "f54b6bcc-3638-4437-83c8-1f76631c9403"
  }
  ```

  ```json Attempt event theme={null}
  {
    "id": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
    "auth_uuid": "f54b6bcc-3638-4437-83c8-1f76631c9403",
    "attempt_uuid": "cc8297d4-7877-4c19-8447-75750e3d17ac",
    "type": "attempt",
    "recipient_phone_number": "+33xxxxxxxx",
    "delivery_status": "delivered",
    "price": {
      "amount": 0.0032,
      "currency": "EUR"
    },
    "time": "2023-05-09T12:09:31+0000",
    "mcc": "208",
    "mnc": "01",
    "correlation_id": "f54b6bcc-3638-4437-83c8-1f76631c9403"
  }
  ```

  ```json Delivery status event theme={null}
  {
    "id": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
    "auth_uuid": "f54b6bcc-3638-4437-83c8-1f76631c9403",
    "attempt_uuid": "cc8297d4-7877-4c19-8447-75750e3d17ac",
    "type": "delivery_status",
    "recipient_phone_number": "+33xxxxxxxx",
    "delivery_status": "delivered",
    "time": "2023-05-09T12:09:31+0000",
    "mcc": "208",
    "mnc": "01",
    "correlation_id": "f54b6bcc-3638-4437-83c8-1f76631c9403"
  }
  ```
</CodeGroup>

## How to set up your Webhook

To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below.
You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

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

  <Step title="Pass the URL">
    Add your webhook endpoint URL to your Authentication requests to start
    receiving events.
  </Step>

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

<Info>
  To avoid replaying events, we recommend that you use the `*_uuid` field to
  identify and deduplicate individual events.
</Info>