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

An SMS is confirmed delivered.

message.failedsms

An SMS delivery fails.

message.expiredsms

An SMS expires before delivery.

message.rejectedsms

An SMS is rejected by the carrier.

email.deliveredemail

An email is accepted by the recipient's mail server.

email.bouncedemail

An email hard-bounces. The address is suppressed for future email from the project.

email.complainedemail

The recipient marks an email as spam.

email.failedemail

An email could not be sent.

email.suppressedemail

An email is not sent because the recipient bounced, complained or unsubscribed earlier.

sender_id.approvedsender id

Sailup approves a pending sender ID. It can send now.

sender_id.rejectedsender id

Sailup rejects a pending sender ID.

sender_id.deactivatedsender id

Sailup stops an approved sender ID. It is no longer your default.

sender_id.reactivatedsender id

Sailup restores a deactivated sender ID. Set it as default again if you need to.

All Event Types
[
  "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.

SMS Event
{
  "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"
  }
}
Email Event
{
  "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
  }
}
Sender ID Event
{
  "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.

Request Headers
X-Sailup-Signature: sha256=<hex hmac>
X-Sailup-Timestamp: <unix timestamp>
X-Sailup-Event: <event type>
X-Sailup-Delivery-Id: <uuid>
Verify (Node.js)
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.

Handler (Node.js)
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);
});