{
  "id": "evt_01jnh4zwabf1grfsaq955ej3mt",
  "type": "verify.authentication",
  "payload": {
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.009,
      "currency": "EUR"
    },
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "time": "2025-03-04T17:59:19.067887456Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:21.163921113Z"
}

{
  "id": "evt_01jnh4zwabf1grfsaq955ej3mt",
  "type": "verify.authentication",
  "payload": {
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.009,
      "currency": "EUR"
    },
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "time": "2025-03-04T17:59:19.067887456Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:21.163921113Z"
}

Prelude can notify your application about events using webhooks. You can configure a webhook URL using the callback_url parameter of your request.

​
The event object

​
id
string

The unique identifier of the event.

​
type
string

The type of the event, possible values are:

TypeDescription
verify.authenticationA verification was created and billed
verify.attemptA verification attempt was sent to the user
verify.delivery_statusSent when we receive a delivery status from the carrier
​
payload
object

The payload of the event, whose structure depends on the event type.

​
created_at
RFC3339 date string

The timestamp of the event creation.

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

​
Delivery Statuses

When we receive a delivery status from the carrier, we send a webhook event with the verify.delivery_status type. The status field in the payload indicates the current state of the message delivery.

Here are the possible status values:

StatusCodeDescription
SubmittedsubmittedThe message has been submitted to the carrier.
In Transitin_transitThe message is in transit to the recipient.
DelivereddeliveredThe message was successfully delivered to the recipient.
UndeliverableundeliverableThe message could not be delivered to the recipient.
UnknownunknownThe delivery status cannot be determined due to unspecified issues or lack of detailed information from the carrier or network.