SMS webhooks

Robase fires webhook events at every SMS lifecycle transition. Subscribe to the ones you care about when you register a webhook.

Event types

sms.queued

Fires the moment we accept a POST /v1/sms. Useful for reconciling “we intended to send X” vs “we actually sent X” in your audit log.

{ "type": "sms.queued", "data": { "sms_id": "...", "status": "queued", ... } }

sms.sent

The upstream carrier accepted the message. This is not delivery — just that the carrier acknowledged the handoff.

{ "type": "sms.sent", "data": { "sms_id": "...", "status": "sent", "provider": "beem", "provider_message_id": "beem-a1b2" } }

sms.delivered

The handset confirmed receipt (via the carrier’s delivery report). This is the event you care about for OTP flows.

{ "type": "sms.delivered", "data": { "sms_id": "...", "status": "delivered", "carrier": "mtn_ng", ... } }

sms.failed

A permanent failure after send — the carrier tried but couldn’t deliver. Typically: handset off too long, SIM no longer exists, blacklist.

{ "type": "sms.failed", "data": { "sms_id": "...", "status": "failed", "error_code": "17", "error_message": "handset unreachable" } }

Wallet overage is automatically refunded for permanent failures.

sms.rejected

Pre-send rejection — e.g. phone_invalid, dnd_blocked, or carrier-level sender-ID block. No attempt was made to deliver.

{ "type": "sms.rejected", "data": { "sms_id": "...", "status": "rejected", "error_code": "dnd_blocked" } }

Also refunds overage automatically.

Payload envelope

Every event has the same top-level shape:

{
  "id": "evt_01H8XKQJ3Z...",
  "type": "sms.delivered",
  "created_at": "2026-04-17T10:30:05Z",
  "data": {
    "sms_id": "01H8XKQJ3Z...",
    "to": "+2348012345678",
    "from": "SHUTTLERS",
    "status": "delivered",
    "segments": 1,
    "provider": "beem",
    "provider_message_id": "beem-a1b2c3",
    "carrier": "mtn_ng",
    "error_code": "",
    "error_message": "",
    "cost": { "amount_kobo": 400, "currency": "NGN" }
  }
}

data matches the shape of GET /v1/sms/:id — if you’ve typed your fetch code, the webhook shape is the same.

Signature verification

Same scheme as email: Robase-Signature: t=<unix>,v1=<hex-hmac>, where the HMAC is over {t}.{body} with your webhook’s secret. See Webhooks for the verification code per language.

Common patterns

OTP flow

// 1. User enters phone number.
const { id } = await pm.sms.send({
  to: phone,
  from: 'MYAPP',
  body: `Your OTP is ${code}. Valid for 5 minutes.`,
});
await db.otps.insert({ user_id, code, sms_id: id, status: 'queued' });

// 2. Webhook handler:
app.post('/webhooks/robase', async (req, res) => {
  const event = await verifyAndParse(req);
  if (event.type === 'sms.delivered') {
    await db.otps.update({ sms_id: event.data.sms_id }, { status: 'delivered' });
  }
  if (event.type === 'sms.failed' || event.type === 'sms.rejected') {
    await db.otps.update({ sms_id: event.data.sms_id }, { status: 'failed' });
    await notifyUserToRetry(event.data.sms_id);
  }
  res.status(200).end();
});

Campaign monitoring

app.post('/webhooks/robase', async (req, res) => {
  const event = await verifyAndParse(req);
  if (event.type.startsWith('sms.')) {
    await metrics.increment(`sms.${event.data.status}.count`, {
      carrier: event.data.carrier,
      country: event.data.country,
    });
  }
  res.status(200).end();
});

Delayed DLRs

African carriers sometimes take minutes or even hours to confirm delivery. Don’t tie UI behavior to sms.delivered — use sms.sent as the “we handed it off” signal, and treat sms.delivered as asynchronous confirmation that may arrive later. For OTP-style flows where you need fast feedback, show the user “Code sent — check your messages” as soon as you get sms.sent, and only escalate to “Didn’t get it?” after a 60-second client-side timeout.

Test-mode webhooks

Test-mode sends fire the same events, with test_mode: true in data. Use this to write idempotent webhook handlers — your real production traffic will go through the same code path with the flag off.

Get Started

SMS

Email

Tutorials

SDKs

Event types

Payload envelope

Signature verification

Common patterns

OTP flow

Campaign monitoring

Delayed DLRs

Test-mode webhooks

​Event types

​Payload envelope

​Signature verification

​Common patterns

​OTP flow

​Campaign monitoring

​Delayed DLRs

​Test-mode webhooks

Event types

Payload envelope

Signature verification

Common patterns

OTP flow

Campaign monitoring

Delayed DLRs

Test-mode webhooks