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
→ wallet.transaction.completed / wallet.transaction.reversedWallet Transaction Event Payloads
Fired on every wallet credit or debit completion and on transaction reversal/refund. Use these to maintain real-time balance state in your system.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Code Execution Playground
Request Snippet (CURL)
# wallet.transaction.completed (funding/credit):
{
"event_type": "wallet.transaction.completed",
"data": {
"reference": "TXN-8C7F89B1DEDF4F42",
"amount": "900.00",
"status": "completed",
"category": "funding",
"type": "credit",
"balance_after": "94200.01"
},
"occurred_at": "2026-08-26T12:01:00Z"
}Success Response (200 OK)
{
"event_type": "wallet.transaction.completed",
"title": "Wallet Transaction Completed",
"message": "Reference TXN-8C7F89B1 for NGN 900.00 is now completed.",
"data": {
"reference": "TXN-8C7F89B1DEDF4F42",
"amount": "900.00",
"status": "completed",
"category": "funding",
"type": "credit",
"balance_after": "94200.01",
"channel": "api"
},
"occurred_at": "2026-08-26T12:01:00Z"
}