Web Hooks

Webhooks provide a reliable way to receive real-time notifications about events that occur within the application. Merchants can supply a webhook URL—typically a simple HTTP POST endpoint—where transaction updates and other event data will be sent automatically when triggered.

MOBILE_MONEY: This webhook event is triggered when a merchant successfully receives a payment from a customer using a using mobile money. The payload of the webhook contains detailed information about the transaction and is structured as follows:

Securing webhook is curicial to mitigate security risk. When the request hit the merchant webhook url, it comes with a signature and timestamp header. 

The merchant webhook endpoint should compare the signature and the timestamp before processing the data.

Webhooks are powerful but can be abused if not protected. This code snippet ensures that only legitimate webhook calls (e.g. from Belema) are processed by validating the request signature.

This code secures incoming webhook requests by verifying their HMAC-SHA256 signature to ensure the request comes from a trusted source and hasn't been tampered with.

1. Extract Headers: It retrieves the Signature and Timestamp headers from the request.




2. Generate Signature: Using the merchant’s private key, it computes a new HMAC-SHA256 hash of the timestamp and merchantCode in this string format timestamp:merchantCode. 
   
   




3. Compare Signatures: If the received signature matches the computed one, the request is considered authentic.
   
   

4. Replay Protection: The Timestamp header can be validated to ensure the request is recent, helping protect against replay attacks.
   
   

5. Process Request: If valid, the request body is read and processed; otherwise, an error response is returned.

Note, when doing signature verification for test charge, use your private api key that can be found in your dashboard and for live charge, use your private live api key

Make sure your webhook endpoint is reachable. If we don’t receive a 200 OK response—such as when your server is down—we’ll automatically attempt to retry the webhook up to 5 times.

1. Ensure webhook url is reachable
   
   
2. Have a backup mechanism if web hook fails such as polling
   
   
3. Secure webhook calls by comparing signature and preventing replay attacks
   
   
4. Respond quickly. To prevent timeouts, avoid executing long-running operations or network requests directly within your webhook endpoint. If your framework allows, return a 200 OK response immediately and handle the rest asynchronously. Otherwise, offload heavy tasks to a background job or queue before sending the response.
   
   
5. Be Idempotent. There may be instances where the same webhook event is delivered more than once. To prevent unintended duplicate processing, your webhook handler should be idempotent—meaning handling the same event multiple times should produce the same outcome without side effects, such as granting value to a customer more than once.