If you are new to building payment integrations, webhooks can feel like an extra piece of homework. However, when dealing with real-world financial networks, webhooks are not optional - they are the backbone of a reliable transaction lifecycle. This guide breaks down exactly why webhooks exist, why relying solely on standard API responses will cause data inconsistencies, and how to implement them securely.

​
What is a Webhook? (API vs. Webhook)

Think of a standard API request like ordering food at a drive-thru: you ask for something, wait at the window, and get your food immediately. This is synchronous communication. A Webhook, on the other hand, is like ordering delivery. You place the order, hang up the phone, and go about your day. When the food arrives, the delivery driver rings your doorbell. This is asynchronous communication. Instead of your server constantly asking OneKhusa, “Is it done yet?”, OneKhusa calls your server the moment the status changes.

​
Why Webhooks are Crucial for OneKhusa

When a customer pays you via mobile money (Airtel Money or TNM Mpamba) or a bank account transfer, the transaction lifecycle looks like this:
  1. Your app sends a request to OneKhusa to initiate a payment.
  2. OneKhusa instantly responds with 202-Accepted or 201-Created. At this exact split second, no money has moved.
  3. The customer receives a USSD prompt on their physical phone asking them to enter their PIN to finalise the payment.
  4. The customer might take 5 seconds, 30 seconds, or a full minute to pull out their phone, read the prompt, and type their PIN.
Because your web server cannot (and should not) keep an HTTP request open waiting for a human to type a PIN, the direct response to your initial API call will never tell you if the payment actually succeeded. It only tells you that the process started. The Golden Rule: You must use webhooks to listen for the final SUCCESS or FAILED state before fulfilling an order, unlocking a digital service, or updating a database balance.

​
The Danger of “Polling” (And Why Webhooks Win)

New developers often try to avoid webhooks by writing a loop that calls our GET /collections/getTransactionStatus?sourceRefNo={id} status endpoint every 2 seconds until the transaction completes. This is called polling. While polling works in a small sandbox, it breaks down catastrophically in production:
  • Wasted Resources: If you have 100 users waiting for prompts, your server is making hundreds of unnecessary network requests every minute, burning CPU cycles and memory.
  • Rate Limiting: To protect the network, OneKhusa enforces strict rate limits on API requests per merchant. Aggressive polling will quickly trip the throttling wall (429-Too Many Requests), causing your app to lose visibility into the transaction entirely.
  • Poor User Experience: Webhooks push data the millisecond the carrier clears the funds, delivering a near-instantaneous checkout experience to your users.

​
Webhook Retries

With our advanced webhook engine, the following are the retries configurations to take note when dealing to OneKhusa webhook notifications:

​
Step-by-Step Execution Lifecycle

Here is how a secure, production-grade webhook lifecycle functions during a OneKhusa transaction:

​
1. Configure your listener:

Setup. You expose a public, secure HTTP POST endpoint on your server (e.g., https://api.yourdomain.com/v1/webhooks/onekhusa) and save this URL in your OneKhusa portal -> Developers -> Webhooks page.

​
2. Receive the payload:

Asynchronous Inbound. When a user completes a payment, OneKhusa delivers a POST request to your endpoint containing a structured JSON object detailing the final state of the transaction.

​
3. Validate the cryptographic signature:

Security Check. To prevent malicious actors from sending fake “success” payloads to your server, you must check the X-OneKhusa-Signature HTTP header matches with merchant webhook signature.

​
4. Acknowledge immediately:

HTTP 200 OK. Your server should instantly return an HTTP status code 200 OK to OneKhusa. This tells our engine, “Message received loud and clear.” If your server returns a 500 error, 404 error, or takes longer than 30 seconds to respond, OneKhusa assumes your server is down and enters a retry backoff loop.

​
5. Process asynchronously:

Business Logic. Handoff the transaction payload to a background worker or queue to provision the customer’s purchase. Keep your primary webhook endpoint lean so it can respond to incoming requests instantly.

​
Best Practices for First-Comers

  • Expect Duplicates (Idempotency): In distributed networks, a webhook might occasionally be sent twice due to minor network hiccups. Always ensure your webhook logic looks up the OneKhusa unique transaction reference number in your database first. If it is already marked SUCCESS, acknowledge with a 200 OK and stop processing further business logic.
  • The Polling Backup Loop: While webhooks are the primary driver, internet routing your region can experience occasional downstream fiber drops. Always implement a daily or hourly scheduled script that queries the OneKhusa API for any transactions stuck in a PENDING state for more than 30 minutes to capture any dropped deliveries.
For more details for webhook events available in OneKhusa, refer to Webhook Events to start receiving payment notifications.