Skip to main content

Webhooks Overview

Webhooks let AfriRoute push real-time event notifications to your server as HTTP POST requests, so you don't have to poll the API. When an SMS is delivered, a payment completes, or an identity verification finishes, AfriRoute sends a signed JSON payload to the URL you configure.

🔄 How It Works​

  1. You register an HTTPS endpoint and subscribe to events in the dashboard or via the API.
  2. An event occurs on the AfriRoute platform.
  3. AfriRoute sends a POST to your endpoint with a JSON body and an X-AfriRoute-Signature header.
  4. Your server verifies the signature, processes the event, and responds with 2xx.
  5. If your server does not respond with 2xx, AfriRoute retries with backoff.

📦 Payload Envelope​

Every webhook shares the same envelope:

{
  "id": "evt_9f8a7b6c",
  "event": "sms.delivered",
  "created_at": "2026-05-10T10:30:05Z",
  "data": {
    "message_id": "msg_abc123",
    "to": "+251911234567",
    "status": "delivered",
    "delivered_at": "2026-05-10T10:30:05Z"
  }
}
FieldTypeDescription
idstringUnique event ID — use it for idempotency
eventstringEvent type (e.g. payment.completed)
created_atstringISO 8601 timestamp of the event
dataobjectEvent-specific payload

🧰 Quick Start (Node.js)​

webhook.js
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, data } = req.body;
  // Verify the signature first — see the Security page.
  console.log(`Received ${event}`);
  res.sendStatus(200);
});

app.listen(3000);

🗂️ Event Categories​

CategoryExample Events
SMSsms.delivered, sms.failed
Paymentspayment.completed, payment.failed, payout.completed
Voicevoice.completed, voice.failed
Identityverification.completed, verification.failed

See the full list on the events reference.

💡 Best Practices​

  • Always verify the signature before trusting a payload — see Webhook Security.
  • Respond fast (under 5s) and process heavy work asynchronously.
  • Be idempotent — key off the event id; the same event may arrive more than once.
  • Return 2xx only on success so failures are retried.
  • Use HTTPS — plaintext endpoints are rejected.

📚 Related Resources​

Last Updated: May 2026 | Need help? [email protected]