Creating a Webhook Listener

BVNK sends webhooks for status changes on payment transactions, so it's a good idea to set up a listener in your service to get the most out of the Payments API.

You can specify your Webhook URL inside the settings of each Merchant you create on the BVNK platform.

10561056

Change the URL here at anytime.

Webhooks will be sent as an HTTP POST with Content-Type: application/json containing the payload of the object.

❗️

Webhooks should not be relied upon as the only source of transaction statuses in your integration. Always check the status of the payment on the API after you receive a webhook as further details may be required, such as the final amount paid for the transaction you have been notified about.

📘

You should stop updating transactions in your system after receiving the final webhook from BVNK - this prevents duplicate transaction IDs from affecting your customers.

Acknowledging events

The Payments API product is expecting a 200 status code upon receipt of a webhook that has been successfully sent.

🚧

If your webhook script performs any logic upon receiving a webhook, you should return a 200 status code before completing the logic to prevent timeouts.

Handling duplicate events

Callback endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts. One way of doing this is logging the events you’ve processed, and then not processing the logged ones.

Webhook validation

Webhooks you receive from the Payments API product contain a signature to allow servers to verify the authenticity of the request using a server-side secret key.

For example, if the Merchant ID secret was XYZ, the signature would be calculated as follows:

var payload = {name:'value',amount:100};
var dataToHash;
if(redirect) {
    dataToHash = JSON.stringify(payload);
}
if(webhook) {
    dataToHash = requestUri; /* The URI of this webhook eg: /my-path on https://mydomain.com/my-path */
    dataToHash += queryString; /* eg: myparam=1 on https://mydomain.com/my-path?myparam=1 */
    dataToHash += contentType; /* eg: application/json */
    dataToHash += JSON.stringify(payload);
}
var hasher = CryptoJS.HmacSHA256(dataToHash, "XYZ");
var hashInHex = CryptoJS.enc.Hex.stringify(hasher);
document.getElementById('output').innerHTML = 'Data to hash: '+dataToHash+"<br/>Resulting signature: "+hashInHex;

The signature will be available in the header of the webhook, x-signature.

Every new webhook will have a new value of the x-signature header. Make sure you are comparing the hash to the right header.
You can obtain your Merchant ID Secret key on the "Merchant Details" page in the BVNK portal.


Did this page help you?