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.
UnknownunknownThe delivery status cannot be determined due to unspecified issues or lack of detailed information from the carrier or network.

​
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 Settings->Keys 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.

​
IP Whitelisting