​
Architectural Overview & Integration Principles

In high-volume bulk payment processing, continuously polling APIs to track individual transactions within large payout batches causes performance bottlenecks, rate limiting, and network latency. OneKhusa’s Batch Disbursement Webhooks implement an event-driven model that delivers real-time HTTP callback notifications directly to your application infrastructure whenever batch states or transaction subsets update.

​
Core Event-Driven Flow

When a batch payout is submitted, OneKhusa decouples batch ingestion and queuing from bulk transaction execution.
  1. Ingestion & Validation — Upon receiving a batch request, the validation engine checks parameters, schema integrity, and merchant balance availability.
  2. Asynchronous Execution — Batches are queued and processed asynchronously across mobile money operators (MNOs), bank rails, and card payment networks.
  3. Chunked Event Dispatch — Rather than waiting for thousands of items to settle at once, the webhook engine pushes updates in processed groups (up to 10 transactions per payload) as transactions complete.
  4. Local Handshake & Hand-off — Your receiver validates the event signature, returns an HTTP 200 OK, and hands the event payload off to your background worker queue for internal reconciliation.

​
Batch Webhook Lifecycle Events

Your endpoint listeners can subscribe to five core batch lifecycle events in the OneKhusa Developer Portal:
Note on batch.received: You will receive a batch.received notification even if some individual transactions fail downstream. The batch.failed event is reserved exclusively for scenarios where the entire batch request fails upfront.

​
Integration & Security Standards

To build a reliable batch receiver, adhere to the following technical requirements:

​
1. Cryptographic Identity Verification

Every incoming HTTP POST request includes the signature and event headers:
  • X-OneKhusa-Webhook-Event: The trigger event code (e.g., batch.received, batch.payout.success).
  • X-OneKhusa-Webhook-Signature: The secret signature used to verify authenticity.
Merchant callback endpoints must calculate an identical HMAC hash using the raw HTTP request payload and your merchant webhook secret before processing events. Unverified notifications must be rejected.

​
2. Non-Blocking Asynchronous Processing

Your webhook controller must remain lightweight to avoid callback timeouts. Do not execute synchronous database locks or external third-party API calls within the HTTP thread. Verify the signature, queue the batch payload internally, and return an HTTP 200 OK immediately. OneKhusa’s gateway waits up to 30 seconds for an HTTP response before marking an attempt as timed out.

​
3. Idempotency & Duplicate Handling

Due to network retries, your listener may receive duplicate webhook payloads. Maintain idempotency in your background consumers by tracking unique reference identifiers (such as transactionReferenceNumber or batch identifiers). Duplicate events should be acknowledged with an HTTP 200 OK without triggering double credits or repeated ledger entries.

​
4. Retries & Exponential Backoff

If your endpoint returns a non-200 HTTP code, times out, or experiences downtime, OneKhusa automatically triggers an exponential backoff retry policy. This protects against data loss during temporary server maintenance or infrastructure outages.