Delivery status and webhooks

Follow each message from accepted to delivered, either by fetching it or by receiving signed webhook events.

Message status

A message has one overall status:

StatusMeaning
scheduledWaiting for schedule_at.
queuedAccepted. Nothing has been handed to the network yet.
sendingAt least one recipient has no final result yet.
completedEvery recipient has a final result: delivered, failed, rejected, expired or skipped. It does not mean every recipient was delivered.
failedThe whole message was not sent, for example a scheduled message refused when it was due, or one that could not be queued. failure_reason says why, and any charge was refunded.

Recipient status

Each recipient has its own status. The final ones never change again.

StatusFinalMeaning
scheduledNoThe message has not been sent yet.
queuedNoAccepted, not yet handed to the network.
sentNoHanded to the network, waiting for a delivery receipt.
deliveredYesEvery part reached the handset.
failedYesThe network could not deliver it (UNDELIV or DELETED). Refunded.
rejectedYesThe network refused it (REJECTD). Refunded.
expiredYesThe validity period ran out before delivery, or no receipt arrived within 48 hours. Refunded only when the network reported the expiry.
unconfirmedUnder reviewWe could not confirm whether the network accepted it (a gateway timeout). Not resent and not refunded automatically: our support team reviews these.
skippedYesNot sent because the number is on your Do-Not-Call list (skip_reason: "do_not_call"). Not charged.

For a message in several parts, the recipient takes the status of its worst part, in this order: failed, rejected, expired, unconfirmed, queued, sent. It is delivered only when every part is delivered.

Fetch a message

GET /v1/sms/{id} returns the message in the same shape as the send response, with live statuses. Each recipient also has:

  • carrier_status: the raw network state, such as DELIVRD, UNDELIV, EXPIRED or REJECTD. Null until a receipt arrives.
  • carrier_error: the raw network error code, such as 023, or null.
  • submitted_at and done_at.

The message also has failure_reason (a string, or null). An unknown id, or one that belongs to another account, returns 404 NOT_FOUND.

curl https://api.kpododo.com/v1/sms/6f1c2a9e-1b7d-4c55-9a51-3f0a9d2c8b11 \
  -H "Authorization: Bearer $KPODODO_API_KEY"

List messages

GET /v1/sms lists messages sent through the API (not dashboard campaigns), newest first, without the recipients array. Filter by your reference (exact match). limit is 1 to 100, default 20. The response is { data, has_more, next_cursor }: pass next_cursor as cursor for the next page. It is null on the last page.

curl "https://api.kpododo.com/v1/sms?limit=20&reference=order-1043" \
  -H "Authorization: Bearer $KPODODO_API_KEY"

Webhooks

Add an endpoint in the dashboard under Account > Developer > Webhooks > Add endpoint. Give an HTTPS URL and choose the events you want; choosing none sends every event. The signing secret (whsec_...) is shown once, so store it straight away. Send test fires a sample call.completed event at your endpoint.

Every event has the same envelope:

sms.delivered
{
  "id": "evt_sms_b0c4...",
  "type": "sms.delivered",
  "created_at": "2026-11-01T10:15:09Z",
  "data": {
    "message_id": "uuid",
    "recipient_id": "uuid",
    "to": "+233244000111",
    "from": "MyShop",
    "reference": "order-1043",
    "status": "delivered",
    "parts": 1,
    "carrier_status": "DELIVRD",
    "carrier_error": null,
    "done_at": "2026-11-01T10:15:08Z"
  }
}

Event types

EventWhendata
sms.delivered, sms.failed, sms.rejected, sms.expiredOne per recipient, when a network delivery receipt settles its final result (all parts final).message_id, recipient_id, to, from, reference, status, parts, carrier_status, carrier_error, done_at
call.ringing, call.answered, call.completedProgress of a call placed with POST /v1/calls.call_id, to (masked), status, hangup_cause, billable_seconds
verify.deliveredThe call carrying a verification code was answered. It can arrive twice for one verification (when answered, and again when the call ends), so handle it once per request_id.call_id, request_id, to (masked), status, hangup_cause, billable_seconds
verify.failedThe call carrying a verification code ended without being answered.Same fields as verify.delivered.

Verify signatures

Each delivery is an HTTP POST with a JSON body and these headers:

Request headers
POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: Kpododo-Webhooks/1
X-Kpododo-Timestamp: 1793528109
X-Kpododo-Signature: t=1793528109,v1=5d41402abc4b2a76b9719d911017c592...

To check a delivery came from Kpododo:

  1. Read t (unix seconds) and v1 (hex) from X-Kpododo-Signature.
  2. Reject the request if t is more than 5 minutes away from your current time. This stops an old delivery being replayed.
  3. Compute HMAC-SHA256 of t, a full stop, then the raw request body, using your whole signing secret (including whsec_) as the key.
  4. Compare the hex result with v1 in constant time.
// Express example. The route reads the RAW body: a parsed and re-serialised
// JSON body will not match the signature.
import crypto from "node:crypto";
import express from "express";

const WEBHOOK_SECRET = process.env.KPODODO_WEBHOOK_SECRET; // the whole whsec_... value
const TOLERANCE_SECONDS = 5 * 60;

function parseSignatureHeader(header) {
  const fields = {};
  for (const item of (header ?? "").split(",")) {
    const separator = item.indexOf("=");
    if (separator > 0) fields[item.slice(0, separator).trim()] = item.slice(separator + 1).trim();
  }
  return fields;
}

function isValidSignature(rawBody, signatureHeader) {
  const { t: timestamp, v1: signature } = parseSignatureHeader(signatureHeader);
  if (!timestamp || !signature) return false;

  // Replay protection: refuse anything signed more than 5 minutes from now.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature, "hex");

  // timingSafeEqual throws on different lengths, so check that first.
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

const app = express();

app.post("/webhooks/kpododo", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("X-Kpododo-Signature"))) {
    return res.status(400).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // Answer quickly (within 10 seconds), then do the work.
  res.sendStatus(200);
  handleEvent(event);
});

const processedEventIds = new Set(); // use your database in production

function handleEvent(event) {
  if (processedEventIds.has(event.id)) return; // already handled
  processedEventIds.add(event.id);

  switch (event.type) {
    case "sms.delivered":
      console.log("Delivered to", event.data.to, "for", event.data.reference);
      break;
    case "sms.failed":
    case "sms.rejected":
    case "sms.expired":
      console.log("Not delivered:", event.data.to, event.data.status);
      break;
    default:
      console.log("Unhandled event", event.type);
  }
}

app.listen(3000);

Responding and retries

  • Respond with any 2xx status within 10 seconds.
  • A non-2xx response or a timeout is retried, up to 3 attempts in total, with a short increasing wait between them (about half a second, then about one second).
  • After the third attempt the delivery is marked failed. You can see it under Account > Developer > Webhooks > View deliveries.

Handle each event once

Every event has a unique id. The same event is never delivered twice to one endpoint, but build your handler to be idempotent anyway: store the id of each event you process and ignore any you have already seen. Acknowledge first and do slow work afterwards, so a slow job never turns into a timeout and a retry.

Calls and verification events are covered in voice calls and verification.