Skip to main content

Webhooks

Khaime sends HTTP POST requests to your webhook URL when events occur across the full lifecycle of payments, subscriptions, wallet operations, settlements, disputes, and physical order fulfillment. This is the most reliable way to track transaction state — don’t rely solely on redirect callbacks.

Setup

  1. Go to Khaime Dashboard → Settings → API
  2. Set your Webhook URL (e.g., https://yoursite.com/webhooks/khaime)
  3. Copy your Webhook Secret (whsec_...)
Or set it programmatically:

Envelope Structure

Every webhook delivery shares the same outer envelope regardless of event type:
The event_id is the idempotency key. You must store processed event_id values and skip duplicates — retries reuse the same event_id.

Webhook Headers

Every webhook request includes these headers:

Delivery

Respond to webhooks within 5 seconds with a 200 status. Process the event asynchronously after acknowledging receipt.

Shared Data Types

These types appear across multiple event payloads.

MoneyAmount

All monetary values are in the smallest currency unit (cents for USD, kobo for NGN). Never floats.

MulticurrencyBreakdown

Present on payment and order events. Provides a full breakdown of amounts, fees, and currency conversion.
If the customer and merchant currencies are the same, conversion is omitted and customer_paid equals merchant_gross.

Customer

The id field is present only if the customer has a platform account.

Example Handler