Webhooks

Real-Time Event Notifications

Receive instant notifications when events happen in your KAD integration. Configure webhook endpoints in your dashboard.

Webhook Events

payment.completed

Fired when a payment is successfully processed

payment.failed

Fired when a payment fails or is declined

payment.refunded

Fired when a payment is refunded

settlement.completed

Fired when a merchant settlement is processed

bnpl.approved

Fired when a BNPL application is approved

bnpl.payment_due

Fired 3 days before an instalment is due

escrow.released

Fired when escrow funds are released to the seller

escrow.disputed

Fired when a buyer opens an escrow dispute

virtual_card.transaction

Fired when a virtual card is used for a transaction

Payload & Signature Verification

Every webhook request includes an x-kad-signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature before processing events.

1# Example webhook payload (POST to your endpoint)
2{
3  "event": "payment.completed",
4  "timestamp": "2026-03-22T14:30:00Z",
5  "data": {
6    "payment_id": "pay_7xKj9mNpQ2",
7    "amount": 450.00,
8    "currency": "KAD",
9    "status": "completed",
10    "reference": "INV-2026-001",
11    "customer_email": "buyer@example.com",
12    "metadata": {
13      "order_id": "ORD-1234",
14      "platform": "RunnerStack"
15    }
16  },
17  "signature": "sha256=a1b2c3d4e5f6..."
18}

Retry Policy

If your endpoint returns a non-2xx status code, we retry with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: After 5 minutes
  • Attempt 3: After 30 minutes
  • Attempt 4: After 2 hours
  • Attempt 5: After 24 hours (final attempt)

After 5 failed attempts, the webhook is marked as failed and you are notified via email. You can manually retry failed webhooks from the dashboard.

Best Practices

  • Always verify the webhook signature before processing events.
  • Return a 200 status code quickly. Process events asynchronously.
  • Handle duplicate events idempotently — we may retry on timeout.
  • Use HTTPS endpoints only. We do not deliver to HTTP URLs.
  • Log all webhook payloads for debugging and audit purposes.
← SandboxAPI Reference →