Webhooks
Receive delivery reports (DLR) and inbound (MO) messages, with HMAC signature verification.
Overview
Instead of polling for status, configure webhooks and eSMS will POST events to
your endpoints in real time:
dlr_url- delivery reports: one event per message you sent, when it reaches a final status (deliveredorfailed).mo_url- inbound (MO) messages: replies from recipients.campaign_url- campaign events (campaign.completed) for campaigns and personalised batches.
Every request is signed with HMAC-SHA256 so you can verify it came from eSMS.
Configure endpoints
Set your URLs in Settings > Webhooks in the dashboard (delivery attempts are listed under Developers > Webhook Logs), or over the API:
GET https://sms.esmsafrica.io/api/webhooks
PUT https://sms.esmsafrica.io/api/webhooks
POST https://sms.esmsafrica.io/api/webhooks/test
POST https://sms.esmsafrica.io/api/webhooks/rotate-secretcurl -X PUT https://sms.esmsafrica.io/api/webhooks \
-H "Authorization: Bearer esms_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"dlr_url": "https://example.com/hooks/dlr",
"mo_url": "https://example.com/hooks/mo",
"campaign_url": "https://example.com/hooks/campaigns",
"is_active": true
}'GET /api/webhooks returns your current config including the signing_secret
(created on first use; team members below admin see it masked). PUT creates
the config if needed and returns {"status": "updated"};
send an empty string to clear a URL, and omit a field to leave it unchanged.
API keys need the webhooks scope for these endpoints.
Endpoints must be publicly reachable - private, loopback and metadata addresses
are refused by an SSRF guard.
POST /api/webhooks/test sends sample signed DLR and MO events to your
configured URLs so you can verify your integration end to end.
Delivery report (DLR) payload
Delivered to your dlr_url. The event is message.<status>, e.g.
message.delivered or message.failed.
{
"event": "message.delivered",
"message_id": "msg_abc123",
"status": "delivered",
"phone": "+254712345678",
"sender_id": "MyApp",
"segments": 1,
"encoding": "GSM7",
"environment": "live",
"livemode": true,
"cost": 0.0093,
"cost_currency": "USD",
"batch_id": null,
"campaign_id": null,
"error_code": null,
"error_message": null,
"retry_count": 0,
"delivered_at": "2026-08-14T12:30:04+00:00",
"failed_at": null
}cost is what your wallet was charged for the message, in cost_currency
(your wallet currency, normally USD). It is the same figure the send response,
the messages API and your reports show, for
domestic, custom-priced and international sends alike. batch_id is set
for messages sent with Bulk SMS,
personalised batches and
campaigns; campaign_id is set when the
message belongs to a campaign (including personalised batches).
On a delivery failure the event is message.failed, status is failed,
error_code carries the failure reason and failed_at is set.
Inbound (MO) payload
Delivered to your mo_url when a recipient replies:
{
"event": "message.inbound",
"message_id": "mo_def456",
"from": "+254712345678",
"to": "MyApp",
"text": "YES",
"keyword": null,
"opt_out": false
}keyword and opt_out are set when the reply is a STOP/START keyword - see
Opt-outs.
Messages that arrive on a Two-Way SMS short code
are delivered to the keyword's own webhook_url (falling back to mo_url) as
message.inbound events with extra fields (keyword, code, body_without_keyword,
conversation_id, matched_by) and a two_way block. Opt-outs on a short code also send
two_way.opt_out / two_way.opt_in events. See
Two-Way SMS webhooks for the full payloads and
the retry schedule (1m, 5m, 30m, 2h, 8h).
Campaign events
When a campaign (or personalised batch) finishes sending, a signed
campaign.completed event is POSTed to the campaign's callback_url, or else
to your account campaign_url. Nothing is sent when neither is set.
{
"event": "campaign.completed",
"campaign_id": 482,
"batch_id": "6f0f5c55-6a2e-4bb1-9c39-2a6f1b6c7d10",
"name": "October payment reminders",
"status": "completed",
"environment": "live",
"livemode": true,
"recipients": 12840,
"sent": 12799,
"failed": 41,
"skipped": 18,
"spent": 153.6,
"currency": "USD",
"tags": ["october"],
"started_at": "2026-10-22T08:05:00+00:00",
"completed_at": "2026-10-22T08:31:10+00:00",
"report_url": "https://sms.esmsafrica.io/campaigns/482"
}"Completed" means every recipient was handed to the networks (or skipped);
delivery reports keep arriving afterwards as message.* events and in the
campaign report. spent is in your
wallet currency (charges minus refunds). The event is signed exactly like DLR
events (same headers, same signing_secret), so the SDK helpers
(verifyWebhook / verify_webhook / VerifyWebhook) verify it. A failed
delivery is retried after 1m, 5m, 30m, 2h and 8h; every attempt is logged in
GET /api/webhook-deliveries.
Headers
| Header | Description |
|---|---|
X-Webhook-ID | Unique event ID (evt_...). |
X-Webhook-Signature | sha256=<hex> HMAC of the raw request body, keyed by your signing_secret. |
Content-Type | application/json. |
Verifying the signature
Compute HMAC-SHA256 over the raw request body with your signing_secret and
compare it (constant-time) to the hex in X-Webhook-Signature after the
sha256= prefix.
import crypto from "node:crypto";
// Use the raw body, e.g. express.raw({ type: "application/json" })
function verify(req, secret) {
const header = req.get("X-Webhook-Signature") || "";
const expected =
"sha256=" +
crypto.createHmac("sha256", secret).update(req.body).digest("hex");
const a = Buffer.from(header);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post("/hooks/dlr", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(req, process.env.ESMS_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString());
// ... handle event.status / event.event
res.sendStatus(200);
});import hashlib
import hmac
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = "your_signing_secret"
@app.post("/hooks/dlr")
def dlr():
raw = request.get_data() # raw bytes, before JSON parsing
expected = "sha256=" + hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
header = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(expected, header):
abort(401)
event = request.get_json()
# ... handle event["status"] / event["event"]
return "", 200Delivery & retries
Respond with a 2xx status within 15 seconds. A DLR is sent once per message,
when it reaches a final status (delivered or failed). A failed delivery is
retried twice (after ~5s and ~15s); every attempt is logged - list them with
GET /api/webhook-deliveries and re-send one with
POST /api/webhook-deliveries/{id}/replay. Rotate your secret any time with
POST /api/webhooks/rotate-secret (this returns a new signing_secret).