eSMS AfricaeSMS Africa
API ReferenceSMS API

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 (delivered or failed).
  • 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-secret
curl -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

HeaderDescription
X-Webhook-IDUnique event ID (evt_...).
X-Webhook-Signaturesha256=<hex> HMAC of the raw request body, keyed by your signing_secret.
Content-Typeapplication/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.

Node.js (Express)
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);
});
Python (Flask)
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 "", 200

Delivery & 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).

On this page