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
→ billpayment.completed / billpayment.failedBill Payment Event Payloads
Fired when a bill payment transaction is completed or failed. Includes full token (electricity), biller metadata, and refund status.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Code Execution Playground
Request Snippet (CURL)
# billpayment.completed:
{
"event_type": "billpayment.completed",
"data": {
"reference": "BP-3F4EC47E85704ABB",
"amount": "1000.00",
"status": "completed",
"category": "electricity",
"token": "26362054405982757802 | Units: 14.8 kWh",
"channel": "api"
},
"occurred_at": "2026-08-26T12:00:00Z"
}Success Response (200 OK)
{
"event_type": "billpayment.completed",
"title": "Electricity Bill Completed",
"message": "Service reference BP-3F4EC47E for NGN 1,000.00 is completed.",
"data": {
"reference": "BP-3F4EC47E85704ABB",
"amount": "1000.00",
"status": "completed",
"category": "electricity",
"biller": "Ikeja Electric - IKEDC",
"customer_id": "1111111111111",
"customer_name": "OBAFEMI AWOLOWO",
"token": "26362054405982757802 | Units: 14.8 kWh",
"channel": "api"
},
"occurred_at": "2026-08-26T12:00:00Z"
}