Webhooks

Inbound SMS Webhook

When an inbound SMS is received, SendAfrica sends a POST request to your webhook URL:

{
  "event": "sms.inbound_received",
  "from": "+255712345678",
  "text": "Hello, I need assistance",
  "message_id": "msg_98124"
}

Signature Verification

Header: X-Webhook-Signature (HMAC SHA-256 hex digest)

Python (FastAPI)

import hmac, hashlib
 
def verify_webhook(secret, body, signature):
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Node.js

const crypto = require('crypto');
 
function verifyWebhook(secret, body, signature) {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Agent Webhook Integration

The SendAfrica Agent includes a built-in webhook endpoint for processing inbound SMS.

Endpoint: POST /webhooks/sendafrica

Set the webhook secret in your .env file:

AGENT_WEBHOOK_SECRET=your-hmac-secret-here

Delivery Status Webhooks

{
  "event": "sms.delivery_status",
  "message_id": "msg_abc123",
  "status": "delivered",
  "delivered_at": "2024-01-15T10:30:00Z"
}

Status Values: sent, delivered, failed, expired

Best Practices

1. Always verify signatures
2. Respond quickly — Return a 200 status within 5 seconds
3. Process asynchronously — Queue messages for background processing
4. Handle retries — SendAfrica retries failed deliveries with exponential backoff
5. Log everything — Keep a record of all webhook events