Webhooks are configured per sending list in the dashboard under your list’s Delivery Forwarding settings. Each webhook subscribes to one or more event types. Select Click explicitly to receive clicks; existing subscriptions and the defaults for new webhooks remain
delivery, reply, and unsubscribe. You can send a synthetic test event from a saved webhook to verify your endpoint without recording a real click.Event Types
Trial SMS account events
Trial SMS uses the existing signed account webhook subscriptions described in Webhook signing, independently of the per-list forwarding format below. Receipts usemessage.delivered or message.failed; replies use message.reply; applicable STOP events use contact.opted_out. Trial events include trial: true.
An unknown submission failure carries delivery_uncertain: true and is_terminal: false. It does not prove non-delivery; a later receipt can reconcile the message without replacing the original failure event. Do not automatically resend.
Replies retain the original account owner after trial expiry, number reuse or retirement. message_id and sending_list_id can be null. Only proven outgoing correlation includes trial_campaign_id and the original metadata. Events retain the existing signing, retries, stable event IDs and replay behavior. Callback routing continues when new trial work is disabled, subject to normal backend availability. No automatic SMS acknowledgement is sent.
Sending-list forwarding events
Request Format
Each POST contains anevents array. Delivery, reply, and unsubscribe events are grouped by processing cycle; click notifications currently contain one event per request. Each event has a type, an ISO-8601 timestamp, and a data object whose fields depend on the event type. An event may also have a stable event_id; click events always do. Older delivery, reply, and unsubscribe events may omit it.
Delivery Event
Sent when a delivery status update is received for a message you sent.Not every route currently emits
delivery events. Click notifications depend on a tracked message link and an explicit click subscription, independently of delivery-event support.Delivery Statuses
delivered is the success terminal state. The exact vocabulary varies by carrier route — some routes pass the carrier’s own status through verbatim, so you may also see intermediate values (e.g. sent, accepted). Treat any value other than delivered as non-success, and any value you don’t recognize as non-terminal.
Reply Event
Sent when a contact sends an inbound SMS to your list number. Every inbound message emits areply event — including opt-out keywords. When a message is an opt-out, an unsubscribe event is emitted in addition to the reply, so a contact who texts STOP produces both a reply and an unsubscribe (typically in the same batch). To act on opt-outs, key off the unsubscribe event — do not assume a reply means the contact stayed subscribed. Replies are also stored and viewable in the dashboard under Sending > Inbox, and from the Recent Replies tab in Contact Lookup. Like every event, it arrives inside the events array (see Request Format).
message_id is an opaque identifier — do not assume a fixed length or format. Store them as variable-length strings.from is your sending list number; to is the contact who replied; text is their message body.
Unsubscribe Event
Sent when a contact is opted out — an opt-out keyword reply, a carrier spam complaint, or repeated hard delivery failures. The opt-out matcher is intentionally broad: it recognizes STOP, STOPALL, UNSUBSCRIBE, QUIT, CANCEL, END, REMOVE, OPTOUT and many common variants and phrasings (e.g. “stop texting”, “take me off the list”, “no more texts”), plus spam-complaint and abuse language — treat these as examples, not an exhaustive list. Like every event, it arrives inside theevents array (see Request Format).
active: false) on the corresponding list. Future sends are blocked automatically. See Compliance for the auto-removal rules.
Re-subscription does not emit a dedicated event. When a previously opted-out contact opts back in (an opt-in keyword such as START, UNSTOP, SUBSCRIBE, OPTIN), they are re-subscribed and sending resumes — but there is no
resubscribe webhook event. The only signal you receive is the ordinary reply event carrying their inbound text (e.g. "Start"). If you mirror subscription state from webhooks, detect opt-ins from the reply body — do not expect a counterpart to the unsubscribe event.A double opt-in re-confirmation hold emits no event; its release rides the ordinary
reply. A journey double opt-in step can be configured to ask an already-subscribed contact to re-confirm. While that request is outstanding the contact is held at active: false and sends are blocked — for as long as the confirmation window runs, up to 168 hours — but no unsubscribe event is emitted, because the contact did not opt out. If they reply Y, YES, or CONFIRM in time, the hold is released, but there is no dedicated event for that either — the only signal is the ordinary reply event carrying their inbound text, exactly like a re-subscription. If the window closes with no reply, nothing is emitted at all. If you mirror subscription state from webhooks, a contact can go non-sendable and later sendable again with no event beyond that generic reply; read the current state from the API when it matters.Click Event
Sent for each captured request to a tracked link associated with a message. Bots and repeat clicks are included; a bot click is not a human engagement signal. Standalone links that are not associated with a message do not emit this event.
Account-level endpoints use
message.clicked and the same data fields inside the signed event envelope. Their list_id may be null when the message and account are verified but a valid sending list cannot be resolved. List notifications require a verified list.
Click recording runs asynchronously. A service interruption before recording completes can cause a missed click notification. Recovery and retries apply after the click has been recorded.
Delivery Semantics
- Batching cadence: delivery, reply, and unsubscribe events are collected on a short polling cycle — roughly every 5 seconds. This is best-effort, not a guaranteed interval. Clicks are delivered asynchronously in single-event batches.
- Timeout: your endpoint must respond within 10 seconds. Return a 2xx status quickly and process events asynchronously.
- Legacy event retries: delivery, reply, and unsubscribe notifications remain best-effort; a non-2xx response or timeout is logged but not retried.
- Click retries: failed click deliveries are retried up to five times, after roughly 1m, 5m, 15m, 1h, and 4h. Pending click work survives worker restarts. Exhausted list click deliveries have no replay API. Disabling/removing an endpoint or removing its click subscription prevents pending attempts; it does not cancel an HTTP request already in progress. Re-enabling it does not revive older work.
- Duplicates and status revisions: dedupe on
event_idwhen present. Carrier receipts can be redelivered upstream, and a later receipt can revise a message’s status (e.g.deliveredcorrected tofailed). For delivery events without an ID, dedupe onmessage_id+status(orprovider_message_id+status) and let the latest received status win. - Authentication: if your webhook has a secret configured, every request includes it in the
X-Webhook-Secretheader — compare it against your stored value before trusting the payload.
Next Steps
Webhooks Integration
Configure webhook endpoints
Send Message
Send a message to trigger events