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
→ ussd.session.completedUSSD Session Event Payloads
Fired when a USSD session completes (user-terminated via END response) or times out. Contains full session traversal path.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Code Execution Playground
Request Snippet (CURL)
# ussd.session.completed:
{
"event_type": "ussd.session.completed",
"data": {
"session_id": "sess_MTN_201910291828000000012345",
"phone_number": "+2348012345678",
"service_code": "*123*001#",
"network": "MTN",
"text_input": "1*2",
"status": "completed",
"duration_seconds": 42
},
"occurred_at": "2026-08-26T12:03:00Z"
}Success Response (200 OK)
{
"event_type": "ussd.session.completed",
"data": {
"session_id": "sess_MTN_201910291828000000012345",
"phone_number": "+2348012345678",
"service_code": "*123*001#",
"network": "MTN",
"text_input": "1*2",
"status": "completed",
"duration_seconds": 42
},
"occurred_at": "2026-08-26T12:03:00Z"
}