Webhooks

Subscribe to real-time events, verify signatures, and manage webhook endpoints through the AfriRoute API.

Webhook Management API

Use the endpoint paths below with your configured BASE_URL.

POST /api/v1/webhooks creates a webhook endpoint
GET /api/v1/webhooks lists configured endpoints
PUT /api/v1/webhooks/{webhookId} updates endpoint settings
DELETE /api/v1/webhooks/{webhookId} removes an endpoint

Event Types

Event	Description
message.delivered	Message successfully reached the handset
message.failed	Delivery failed (e.g. carrier blocked, invalid number)
call.completed	Voice call ended, includes duration and cost
payment.received	Mobile money collection confirmed
otp.verified	Verification flow completed successfully

Secure your webhooks

AfriRoute signs every webhook request so you can verify it was sent by us.

Retrieve your webhook secret from the Console.
Look for the x-afriroute-signature header.
Calculate the HMAC SHA256 of the payload body using your secret.
Compare the hashes.

Retry Schedule

If your endpoint returns anything other than a 2xx status code, AfriRoute retries delivery with backoff while preserving the original payload and signature headers:

Immediately
After 1 minute
After 5 minutes
After 30 minutes
After 3 hours

Live Examples

Node.js Verify

javascript

1const crypto = require('crypto');
2
3function verifySignature(req, secret) {
4  const signature = req.headers['x-afriroute-signature'];
5  const payload = JSON.stringify(req.body);
6  
7  const expected = crypto
8    .createHmac('sha256', secret)
9    .update(payload)
10    .digest('hex');
11    
12  if (signature !== expected) {
13    throw new Error('Invalid signature');
14  }
15}

Demo-mode examples are safe to run and show request shapes.

Event Types

Event	Description
message.delivered	Message successfully reached the handset
message.failed	Delivery failed (e.g. carrier blocked, invalid number)
call.completed	Voice call ended, includes duration and cost
payment.received	Mobile money collection confirmed
otp.verified	Verification flow completed successfully