{
  "id": "evt_01htjex3pre54tywgzsdg1jnbn",
  "type": "transactional.message.created",
  "payload": {
    "id": "tx_01htjet67afxhta23j7dtekneh",
    "to": "+3361234567",
    "created_at": "2024-04-03T17:08:01.349000489Z",
    "expires_at": "2024-04-03T17:08:01.349000489Z",
    "customer_uuid": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
    "variables": {
      "name": "John"
    },
    "fee": {
      "amount": "0.009",
      "currency": "EUR"
    },
    "correlation_id": "8709c4f8-78b4-4a3c-8167-e99164424d0f"
  },
  "created_at": "2024-04-03T17:08:01.36881397Z"
}

{
  "id": "evt_01htjex3pre54tywgzsdg1jnbn",
  "type": "transactional.message.created",
  "payload": {
    "id": "tx_01htjet67afxhta23j7dtekneh",
    "to": "+3361234567",
    "created_at": "2024-04-03T17:08:01.349000489Z",
    "expires_at": "2024-04-03T17:08:01.349000489Z",
    "customer_uuid": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
    "variables": {
      "name": "John"
    },
    "fee": {
      "amount": "0.009",
      "currency": "EUR"
    },
    "correlation_id": "8709c4f8-78b4-4a3c-8167-e99164424d0f"
  },
  "created_at": "2024-04-03T17:08:01.36881397Z"
}

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
transactional.message.createdThe message was sent successfully
transactional.message.pending_deliveryThe message is pending delivery
transactional.message.deliveredDelivery succeeded
transactional.message.failedDelivery failed, see status and reason.
transactional.message.unknownUnknown delivery, see status and reason.
​
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.

​
correlation_id
string

A user-defined identifier to correlate the event with your internal system.

​
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 Transactional 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

Failed delivery statuses come with a status field which can have two values: failed or expired.

An additional reason provides more information about the failure. Some of these may be retriable until we reach the expiry window defined in the expires_at field of the Send Message request.

Here are the possible reason values:

ReasonCodeDescriptionRetriable
Unavailable RecipientunavailableThe recipient is unavailable due to a temporary problem (e.g. no cell network).
Generic ReasongenericNo detailed information has been received from the underlying carrier.
Network IssuenetworkThe recipient’s carrier network is temporary unreachable.
Unknown Recipientunknown_recipientThe number is not associated with an active line.
Insufficient Balanceinsufficient_balanceYour balance is insufficient to make an attempt.
Carrier Rejectedcarrier_rejectedThe recipient’s mobile carrier blocked the message (e.g. lack of registration, invalid content or local traffic restrictions).
UnknownunknownThe delivery status cannot be determined due to unspecified issues or lack of detailed information from the carrier or network.