Skip to main content
{
  "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. There are two types of webhooks:
  1. Message delivery webhooks: Configure using the callback_url parameter of your send request to receive delivery updates
  2. Subscription management webhooks: Configure through your subscription management config (managed by our Customer Success team) to receive subscription events (STOP, START, HELP)

​
Message delivery events

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

​
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 Notify API requests to start receiving message delivery 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

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 — Prelude will automatically retry delivery 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.

​
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

​
Subscription management events

When users interact with your messages by sending subscription keywords (STOP, START, or HELP), Prelude will send webhook events to the callback URL configured in your subscription management config.

​
Subscription event object

​
id
string
The unique identifier of the event.
​
type
string
The type of subscription event:
TypeDescription
marketing.subscription.stopUser opted out by sending STOP keyword
marketing.subscription.startUser opted back in by sending START keyword
marketing.subscription.helpUser requested help by sending HELP keyword
​
payload
object
​
action
string
The subscription action keyword sent by the user. Possible values: STOP, START, HELP.
​
from
string
The phone number that sent the subscription keyword (E.164 format).
​
to
string
The destination phone number (your short code or long code).
​
received_at
RFC3339 date string
The timestamp when the subscription keyword was received.
​
created_at
RFC3339 date string
The timestamp of the event creation.

​
Example subscription webhooks

{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "marketing.subscription.stop",
  "payload": {
    "action": "STOP",
    "from": "+33612345678",
    "to": "36184",
    "received_at": "2025-10-24T08:59:10.736909995Z"
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}

​
Handling subscription events

When you receive a subscription event:
  • STOP: The user has been automatically unsubscribed. Subsequent API calls for this phone number will return an error.
  • START: The user has been resubscribed and can receive marketing messages again.
  • HELP: The user requested information. A default help message is automatically sent, but you may want to log this event.