Realtime
Webhooks & Event Delivery
Receive real-time signed HTTP notifications for transaction updates, bill fulfillment tokens, SMS delivery reports, USSD session completions, and wallet top-ups.
Architecture & Integration Guidelines:
- All webhook payloads are signed with HMAC-SHA256 using your secret and delivered via the X-CBI-Signature header.
- Verify the signature on every request before executing business logic to prevent replay attacks.
- Your endpoint must respond with HTTP 2xx within 10 seconds. Failed deliveries are retried up to 5 times with exponential backoff.
- Subscribe to specific events or use '*' to receive all events.
POST
→ sms.single.sent / sms.single.failed / sms.delivery_statusSMS Event Payloads
Fired when an SMS is dispatched to the gateway, fails dispatch, or when a DLR (delivery status report) is received from the telco.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Code Execution Playground
Request Snippet (CURL)
# sms.single.sent:
{
"event_type": "sms.single.sent",
"data": { "reference": "msg_78123891", "phone": "+2348012345678",
"sender_id": "CBISUITE", "status": "sent", "units": 1, "cost": "4.50" },
"occurred_at": "2026-08-26T12:02:00Z"
}Success Response (200 OK)
{
"event_type": "sms.single.sent",
"title": "SMS Sent",
"data": {
"reference": "msg_78123891",
"phone": "+2348012345678",
"sender_id": "CBISUITE",
"status": "sent",
"units": 1,
"cost": "4.50"
},
"occurred_at": "2026-08-26T12:02:00Z"
}