Webhooks and delivery events

SendAfrica has two different callback boundaries. The Agent service can receive verified inbound SMS events for an automated reply workflow. Delivery reports from the SMS provider are processed by the SendAfrica API and are not delivered to the Agent as an application webhook.

Agent inbound SMS callback

The Agent endpoint is:

POST https://agent.example.com/webhooks/sendafrica

A provider or trusted gateway may send an inbound event such as:

{
  "event": "sms.inbound_received",
  "from": "+255712345678",
  "text": "Hello, I need assistance",
  "message_id": "provider-message-98124"
}

The Agent validates the callback, acknowledges it with a small queued response, and processes the assistant pipeline asynchronously. If AGENT_WEBHOOK_SECRET is set, the request must include the HMAC SHA-256 hex digest in X-Webhook-Signature or X-Signature.

import hashlib
import hmac
 
 
def verify_webhook(secret: str, raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Verify the raw request body before parsing JSON. Return 401 for an invalid signature, 400 for invalid JSON or missing from/text, and do not log secrets or full message bodies.

Delivery status processing

The SendAfrica API receives Africa’s Talking delivery reports on its provider callback route. The provider callback is authenticated with the API’s configured provider callback token. SendAfrica normalizes provider status values, updates the account-owned message log, and applies any late-failure refund exactly once through an idempotent ledger operation.

Applications should read delivery state from SendAfrica SMS logs using the public SA-<uuid> message ID returned by the API. A successful SMS submission is not proof of handset delivery. Typical public states include sent, delivered, failed, and rejected; the exact provider status is preserved separately where available.

Do not build an application-side HMAC consumer for delivery events from the Agent. The Agent’s /webhooks/sendafrica route is for inbound SMS automation, while delivery reconciliation belongs to the SendAfrica API and its message-log API.

Fast acknowledgement and retries

For inbound callbacks, acknowledge quickly and let the Agent create the background task. Provider gateways may retry a callback, so configure a stable provider message ID; the Agent uses that ID to derive an idempotency key for automatic replies. Do not assume that a callback has been durably processed merely because the HTTP response was accepted.

For delivery reporting, use the SendAfrica API’s durable message logs as the source of truth. Poll or reconcile from logs after submission, and treat a delivered message as terminal. Do not overwrite a delivered state with a later failure in application code.

Configuration

AGENT_WEBHOOK_SECRET=replace-with-a-long-random-secret

Keep the Agent callback endpoint behind TLS and a trusted gateway. Restrict accepted hosts and origins with AGENT_ALLOWED_HOSTS and AGENT_ALLOWED_ORIGINS; those settings apply to the Agent HTTP service and are separate from SendAfrica provider callback configuration.