Skip to main content
{
  "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 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:
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. 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.
UnknownunknownThe 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: 
34.252.67.209
52.30.192.161
34.248.153.151