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
/api/v1/core/webhooks/Register Webhook Endpoint
Configure a new outbound webhook endpoint URL, secret, and event subscriptions.
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Request Body
{
"url": "https://api.yourdomain.com/cbi-events",
"secret": "whsec_your_random_secret_32chars",
"events": [
"billpayment.completed",
"billpayment.failed",
"wallet.transaction.completed",
"sms.single.sent"
],
"is_active": true,
"timeout_seconds": 10,
"retry_count": 5
}Code Execution Playground
Request Snippet (CURL)
curl -X POST "https://backend.cbivas.com/api/v1/core/webhooks/" \
-H "Authorization: Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"url":"https://api.yourdomain.com/cbi-events","secret":"whsec_your_secret","events":["billpayment.completed","wallet.transaction.completed"],"is_active":true}'Success Response (200 OK)
{
"id": "wh_891238ab",
"url": "https://api.yourdomain.com/cbi-events",
"events": [
"billpayment.completed",
"billpayment.failed"
],
"is_active": true,
"created_at": "2026-08-26T12:00:00Z"
}