{
  "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_01jnh50110f1gt7n74yb6kcrzb",
  "type": "verify.attempt",
  "payload": {
    "carrier_information": {
      "mcc": "208",
      "mnc": "10"
    },
    "delivery_status": "delivered",
    "id": "att_3v9s0v9gzt8hws0cp753q4gj0c",
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.03,
      "currency": "EUR"
    },
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "channel": "sms",
    "time": "2025-03-04T17:59:21.375073507Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:25.984640901Z"
}

{
  "id": "evt_01jnh500a6frv9ky0wn4r6aycv",
  "type": "verify.delivery_status",
  "payload": {
    "attempt_id": "att_3v9s0v9gzt8hws0cp753q4gj0c",
    "carrier_information": {
      "mcc": "208",
      "mnc": "10"
    },
    "id": "dls_1mzny4yepa9berf8hemgys2391",
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.03,
      "currency": "EUR"
    },
    "status": "delivered",
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "channel": "sms",
    "time": "2025-03-04T17:59:25.129596712Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:25.254545815Z"
}

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

string

The unique identifier of the event.

string

The type of the event, possible values are:

Type	Description
`verify.authentication`	A verification was created and billed
`verify.attempt`	A verification attempt was sent to the user
`verify.delivery_status`	Sent when we receive a delivery status from the carrier

object

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

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.

Implement the handler

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

Pass the URL

Add your webhook endpoint URL to your Verification requests to start receiving events.

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

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:

Status	Code	Description
Submitted	`submitted`	The message has been submitted to the carrier.
In Transit	`in_transit`	The message is in transit to the recipient.
Delivered	`delivered`	The message was successfully delivered to the recipient.
Undeliverable	`undeliverable`	The message could not be delivered to the recipient. Common reasons include: the phone number is invalid or not in service, the device is turned off or unreachable, the carrier rejected the message, the number is blocked or barred from receiving SMS, or network congestion and routing failures.
Unknown	`unknown`	The delivery status cannot be determined due to unspecified issues or lack of detailed information from the carrier or network.

Delivery statuses are indicative, but they may not always be fully reliable. Depending on the market, a “delivered” confirmation can indicate delivery to the mobile network operator, the cell tower, or — in some cases — the end user’s handset.

Cost reconciliation can take up to 15 minutes. During this window, the billed amount may not yet reflect the final cost of the message.

Security

Prelude’s webhooks support the following security features:

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. 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. To enable the webhook signature, go to the Prelude dashboard in the Verify API->Configure->Webhooks section and generate a webhook signing key for 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 same signing key is used for both the Verify and Notify APIs.

IP Whitelisting

You should whitelist the following IP addresses to ensure that your webhook endpoint receives events from Prelude:

252.67.209
30.192.161
248.153.151

Test NumbersLearn how to confirm that your integration is working properly by simulating verifications without incurring charges using special test numbers.

{
  "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_01jnh50110f1gt7n74yb6kcrzb",
  "type": "verify.attempt",
  "payload": {
    "carrier_information": {
      "mcc": "208",
      "mnc": "10"
    },
    "delivery_status": "delivered",
    "id": "att_3v9s0v9gzt8hws0cp753q4gj0c",
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.03,
      "currency": "EUR"
    },
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "channel": "sms",
    "time": "2025-03-04T17:59:21.375073507Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:25.984640901Z"
}

{
  "id": "evt_01jnh500a6frv9ky0wn4r6aycv",
  "type": "verify.delivery_status",
  "payload": {
    "attempt_id": "att_3v9s0v9gzt8hws0cp753q4gj0c",
    "carrier_information": {
      "mcc": "208",
      "mnc": "10"
    },
    "id": "dls_1mzny4yepa9berf8hemgys2391",
    "metadata": {
      "correlation_id": "e9156dad-de79-4d47-9e6b-e0c40e9244a4"
    },
    "price": {
      "amount": 0.03,
      "currency": "EUR"
    },
    "status": "delivered",
    "target": {
      "type": "phone_number",
      "value": "+33xxxxxxxx"
    },
    "channel": "sms",
    "time": "2025-03-04T17:59:25.129596712Z",
    "verification_id": "vrf_01jnh4zt8vfq5r71n1sx9yvx5m"
  },
  "created_at": "2025-03-04T17:59:25.254545815Z"
}

Documentation

API Reference

Webhook for the Verify API

The event object

How to set up your Webhook

Delivery Statuses

Security

Webhook Signature

IP Whitelisting

​The event object

​How to set up your Webhook

​Delivery Statuses

​Security

​Webhook Signature

​IP Whitelisting

The event object

How to set up your Webhook

Delivery Statuses

Security

Webhook Signature

IP Whitelisting