Webhook Verification Guide
Verify Kang Open Banking webhook signatures using HMAC-SHA256. Full list of 52 event types, exponential backoff retry policy, and idempotent handling for payment notifications.
Webhook Integration
Receive real-time payment, account and lifecycle notifications via HTTPS webhooks with cryptographic signature verification. Every event includes a stable event_id for safe idempotent handling on the receiver side.
Signature Verification (HMAC-SHA256)
All webhooks are signed using HMAC-SHA256. Verify the X-KOB-Signature header against the raw, unparsed request body using the shared secret you configured for the endpoint.
Node.js
const crypto = require('crypto');
function verify(rawBody, signature, secret) {
const expected = crypto.createHmac('sha256', secret)
.update(rawBody, 'utf8').digest('hex');
// Constant-time comparison
return crypto.timingSafeEqual(
Buffer.from(expected, 'hex'),
Buffer.from(signature, 'hex')
);
}
Python
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
PHP
function verify(string $rawBody, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $rawBody, $secret);
return hash_equals($expected, $signature);
}
Event Types (52 events)
Grouped by domain. Subscribe to only the events you need.
| Domain | Events |
|---|
| Charges | charge.created, charge.pending, charge.succeeded, charge.failed, charge.cancelled, charge.refunded, charge.partially_refunded |
| Refunds | refund.created, refund.succeeded, refund.failed |
| Payouts | payout.created, payout.pending, payout.sent, payout.succeeded, payout.failed, payout.cancelled |
| Transfers | transfer.initiated, transfer.completed, transfer.failed, transfer.reversed |
| Disputes | dispute.opened, dispute.evidence_required, dispute.won, dispute.lost, dispute.closed |
| Settlements | settlement.created, settlement.completed, settlement.failed |
| Subscriptions | subscription.created, subscription.renewed, subscription.cancelled, subscription.payment_failed |
| Accounts (AISP) | consent.authorised, consent.revoked, consent.expired, account.linked, account.unlinked |
| Payments (PISP) | payment.initiated, payment.authorised, payment.completed, payment.rejected, payment.cancelled |
| KYC / Compliance | kyc.submitted, kyc.approved, kyc.rejected, compliance.flagged, sar.filed |
| Loans / Savings | loan.disbursed, loan.repaid, loan.overdue, savings.deposit, savings.withdrawal |
| System | webhook.test |
Retry Policy
Failed deliveries (any non-2xx response or timeout) are retried with exponential backoff over 7 attempts:
| Attempt | Delay |
|---|
| 1 | Immediate |
| 2 | +1 minute |
| 3 | +5 minutes |
| 4 | +30 minutes |
| 5 | +2 hours |
| 6 | +8 hours |
| 7 | +24 hours |
After the 7th failure the event is moved to the dead-letter queue and retained for 30 days. You can replay events from the Developer Console or the POST /v1/webhooks/{id}/replay API.
Per-attempt timeout: 10 seconds. Return any 2xx within that window to acknowledge.
Developer Portal Home | OpenAPI Spec (JSON) | Contact