​
Architectural Overview & Integration Principles

When processing individual payouts — such as real-time supplier payments, withdrawal requests, or direct refunds — relying on synchronous polling to check transaction status introduces latency, rate-limiting overhead, and unnecessary network traffic. OneKhusa’s Single Disbursement Webhooks provide an event-driven, push-based model that notifies your backend infrastructure immediately when an individual payout changes status.

​
Core Event-Driven Flow

For single disbursements, OneKhusa decouples the initial payout submission from final settlement execution.
  1. Payout Initiation — Your system initiates a direct payment request via the Single Disbursement API. OneKhusa validates the request parameters and balance availability, returning an immediate acknowledgement that the transaction is either pending or paid.
  2. Upstream Network Processing — The payment is routed through carrier pathways, such as NATSWITCH (mobile money operators (MNOs), banks), or card settlement channels.
  3. Event Dispatch — Once the payment reaches a final state (successful settlement, processing failure, or post-settlement reversal), the OneKhusa Webhook Engine triggers an HTTP POST request to your configured webhook URL.
  4. Local Handshake & Consumer Queue — Your application validates the incoming payload’s signature, returns an HTTP 200 OK acknowledgement immediately, and hands the event transaction payload off to an internal queue for account reconciliation.

​
Single Disbursement Lifecycle Events

You can configure endpoint listeners in the OneKhusa Developer Portal for the following single disbursement lifecycle events:

​
Integration Standards & Security Architecture

To build a secure and resilient receiver for single disbursement webhooks, ensure your endpoint adheres to these core technical standards:

​
1. Cryptographic Identity Verification

Every incoming HTTP POST transmission includes headers for event identification and signature verification:
  • X-OneKhusa-Webhook-Event: Specifies the event type (e.g., payout.success, payout.failed).
  • X-OneKhusa-Webhook-Signature: The secret cryptographic signature used to verify request authenticity.
Your endpoint must compute an HMAC-SHA512 hash using the raw request payload body and your merchant webhook secret. Compare this value to the signature in X-OneKhusa-Webhook-Signature before accepting the notification. Unverified requests must be rejected immediately.

​
2. Non-Blocking Acknowledgement

To maintain gateway health and avoid webhook timeouts, your HTTP handler must remain lightweight. Avoid running blocking database locks, complex account updates, or third-party email notifications directly inside the incoming HTTP request thread. Validate the signature, enqueue the transaction payload into a background worker (e.g., Redis/Celery, RabbitMQ, SQS), and respond immediately with an HTTP 200 OK. The webhook engine waits up to 30 seconds for an HTTP response before marking the delivery attempt as timed out.

​
3. Idempotent Event Handling

Network retries or latency can occasionally result in duplicate webhook deliveries. Your receiving service should store and track the unique transactionReferenceNumber. If a duplicate notification arrives, your system should acknowledge it with an HTTP 200 OK without re-processing the order, double-crediting balances, or duplicating internal records.

​
4. Delivery Guarantees & Exponential Backoff

If your endpoint is down, undergoing maintenance, or returns a non-200 HTTP code (e.g., 500 Internal Server Error, 503 Service Unavailable), OneKhusa’s engine automatically activates an exponential backoff retry schedule. This ensures temporary system outages do not result in unhandled or dropped payout notifications.