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:
| Status | Meaning |
|---|---|
scheduled | Waiting for schedule_at. |
queued | Accepted. Nothing has been handed to the network yet. |
sending | At least one recipient has no final result yet. |
completed | Every recipient has a final result: delivered, failed, rejected, expired or skipped. It does not mean every recipient was delivered. |
failed | The 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.
| Status | Final | Meaning |
|---|---|---|
scheduled | No | The message has not been sent yet. |
queued | No | Accepted, not yet handed to the network. |
sent | No | Handed to the network, waiting for a delivery receipt. |
delivered | Yes | Every part reached the handset. |
failed | Yes | The network could not deliver it (UNDELIV or DELETED). Refunded. |
rejected | Yes | The network refused it (REJECTD). Refunded. |
expired | Yes | The validity period ran out before delivery, or no receipt arrived within 48 hours. Refunded only when the network reported the expiry. |
unconfirmed | Under review | We could not confirm whether the network accepted it (a gateway timeout). Not resent and not refunded automatically: our support team reviews these. |
skipped | Yes | Not 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 asDELIVRD,UNDELIV,EXPIREDorREJECTD. Null until a receipt arrives.carrier_error: the raw network error code, such as023, or null.submitted_atanddone_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:
{
"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
| Event | When | data |
|---|---|---|
sms.delivered, sms.failed, sms.rejected, sms.expired | One 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.completed | Progress of a call placed with POST /v1/calls. | call_id, to (masked), status, hangup_cause, billable_seconds |
verify.delivered | The 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.failed | The 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:
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:
- Read
t(unix seconds) andv1(hex) fromX-Kpododo-Signature. - Reject the request if
tis more than 5 minutes away from your current time. This stops an old delivery being replayed. - Compute HMAC-SHA256 of
t, a full stop, then the raw request body, using your whole signing secret (includingwhsec_) as the key. - Compare the hex result with
v1in 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.