The V1 API is deprecated. Technical support will end by October 2025 and will be removed by April 2026. No new features nor functionality will be added to the V1 API. Please use the V2 Verify API instead. For more information refer to the V2 Migration Guide.

​
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 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.
{
  "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"
}

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

Implement the handler

Develop a webhook endpoint function to receive event data POST requests.
2

Pass the URL

Add your webhook endpoint URL to your Authentication requests to start receiving events.
3

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.
To avoid replaying events, we recommend that you use the *_uuid field to identify and deduplicate individual events.