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
→ Verify X-CBI-Signature headerSignature Verification Guide
How to verify the X-CBI-Signature HMAC-SHA256 header on every inbound webhook payload before processing.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Code Execution Playground
Request Snippet (CURL)
# Python/Flask signature verification:
import hmac, hashlib
def verify(payload_bytes: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)Success Response (200 OK)
{
"header": "X-CBI-Signature: <hex_digest>",
"algorithm": "HMAC-SHA256",
"key": "Your webhook secret (set during registration)",
"message": "Raw request body bytes"
}