Webhooks
Add a webhook under Webhooks in your project's dashboard, and Sailup will send it a signed POST when an SMS or email reaches its final status, or when Sailup reviews one of your sender IDs. Webhooks are set up in the dashboard only. There is no API for them.
Event types
Webhooks fire for final message outcomes and for Sailup's decisions on your sender IDs, nothing else. You won't get one for in-between states like queued, sent or dispatched, or for registering a sender ID. When you add the endpoint, pick the events you want, or leave the list empty to get all of them.
message.deliveredsmsAn SMS is confirmed delivered.
message.failedsmsAn SMS delivery fails.
message.expiredsmsAn SMS expires before delivery.
message.rejectedsmsAn SMS is rejected by the carrier.
email.deliveredemailAn email is accepted by the recipient's mail server.
email.bouncedemailAn email hard-bounces. The address is suppressed for future email from the project.
email.complainedemailThe recipient marks an email as spam.
email.failedemailAn email could not be sent.
email.suppressedemailAn email is not sent because the recipient bounced, complained or unsubscribed earlier.
sender_id.approvedsender idSailup approves a pending sender ID. It can send now.
sender_id.rejectedsender idSailup rejects a pending sender ID.
sender_id.deactivatedsender idSailup stops an approved sender ID. It is no longer your default.
sender_id.reactivatedsender idSailup restores a deactivated sender ID. Set it as default again if you need to.
[
"message.delivered",
"message.failed",
"message.expired",
"message.rejected",
"email.delivered",
"email.bounced",
"email.complained",
"email.failed",
"email.suppressed",
"sender_id.approved",
"sender_id.rejected",
"sender_id.deactivated",
"sender_id.reactivated"
]Payload
Every payload carries the event that fired, the created_at timestamp, and a data object describing the message or sender ID.
SMS payloads carry the message's id, from (the sender ID), to and status, which always matches the outcome named in event. The older message_id, sender, recipient and delivery_status keys carry the same values and still work, but are deprecated.
Email payloads carry the email's id, which matches the id returned when you sent it, and its type: transactional or promotional. from is what the recipient saw, with the display name when there was one. failure_code says why an email.failed email failed, and is null otherwise. A delivered email can later fire email.bounced or email.complained, so the last event you receive for an id wins.
Sender ID payloads carry the sender ID object. status_reason holds the reason for a rejection or deactivation, and is empty otherwise.
{
"event": "message.delivered",
"created_at": "2026-08-30T18:05:00Z",
"data": {
"id": "58cf292d-417e-4f61-9687-662b845574cf",
"project_id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"from": "Sail",
"to": "+233241234567",
"status": "delivered",
"message_id": "58cf292d-417e-4f61-9687-662b845574cf",
"recipient": "+233241234567",
"sender": "Sail",
"delivery_status": "delivered"
}
}{
"event": "email.delivered",
"created_at": "2026-11-03T01:02:45Z",
"data": {
"id": "29cc7ea2-08ad-4a0b-8d4a-95744cf98f44",
"project_id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"from": "Acme <[email protected]>",
"to": "[email protected]",
"status": "delivered",
"type": "transactional",
"failure_code": null
}
}{
"event": "sender_id.rejected",
"created_at": "2026-11-04T09:12:00Z",
"data": {
"id": "6f1d2c9e-3b7a-4e0f-9a51-2d8c4b7e1f03",
"name": "AcmeShop",
"use_case": "promotional",
"sample_message": "AcmeShop: 20% off everything this weekend.",
"notes": "",
"status": "rejected",
"status_reason": "The name doesn't match the business on the account.",
"is_default": false,
"reviewed_at": "2026-11-04T09:12:00Z",
"created_at": "2026-11-03T15:40:00Z"
}
}Verifying a payload
Every request we send is signed. Recompute the signature by hashing {timestamp}.{raw_body} with HMAC-SHA256 and your webhook secret, then compare it to X-Sailup-Signature after the sha256= prefix. Reject the payload if it does not match.
Check the signature against the raw request body, before you parse it. Parsing and re-serializing the JSON changes the bytes, and then the signature won't match. Your webhook secret is shown once, when you register the webhook in your dashboard.
X-Sailup-Signature: sha256=<hex hmac>
X-Sailup-Timestamp: <unix timestamp>
X-Sailup-Event: <event type>
X-Sailup-Delivery-Id: <uuid>import crypto from "node:crypto";
function isValid(rawBody, headers, secret) {
const timestamp = headers["x-sailup-timestamp"];
const received = headers["x-sailup-signature"].replace("sha256=", "");
const expected = crypto
.createHmac("sha256", secret)
.update(timestamp + "." + rawBody)
.digest("hex");
const a = Buffer.from(received, "hex");
const b = Buffer.from(expected, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Retries
If your endpoint does not return a 2xx response, we retry up to five times with exponential backoff before giving up on that event. Each attempt is recorded separately in the delivery log in your dashboard.
After ten consecutive delivery cycles fail, we disable the webhook and notify the project owner by email. You can re-enable it from the dashboard once the endpoint is fixed, and retry any past delivery from the log.
app.post("/webhooks/sailup", (req, res) => {
if (!isValid(req.rawBody, req.headers, process.env.SAILUP_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
// Acknowledge first, process afterwards. Anything other than a 2xx counts
// as a failed delivery and is scheduled for retry.
res.sendStatus(200);
queue.push(req.body);
});