Listen for events on your account using our webhook options

What are webhooks?

Webhooks are a way for you to subscribe to events that occur when an event involving your business occurs. This guide will walk through what webhooks are and how you can use them in order to get started with integrating them into your application.

A webhook URL is an unauthenticated POST endpoint on your service where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event, including the event's name and the data associated with it. The webhook request body will always take the following properties:

  1. event : This points to the event that initiated the webhook from our end. The various webhook events we support are discussed further later on this page.

  2. data: This holds the data associated with the event that occurred on our end. For example, in the case of a Transaction.Success event, the data property will hold the transaction object.

Supported Webhooks events.

Below is a growing list of Webhook events we support.



This occurs when a previously initiated transaction is successful. A transaction is successful when its status property is success.


This occurs when a previously initiated transaction fails. A transaction is successful when its status property is failed. When the transaction fails, the reason for failure is stored in the failureReason property of the transaction object.


This is triggered when a payout is successful.


This is triggered when a payout fails


This is triggered when a payout request is declined. In this case, the reason for decline will be attached to the reasonForDecline property on the payout request object.


This is triggered when a customer virtual account is credited.

Validating webhooks

Every webhook event payload will contain a hashed authentication signature in the header which is computed by generating a hash from concatenating your API key and request body, using the HMAC SHA512 hash algorithm.In order to verify this signature came from IvoryPay, you simply have to generate the HMAC SHA512 hash and compare it with the signature received.

var crypto = require('crypto');
var secret = process.env.SECRET_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    var hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body.data), 'utf8').digest('hex');
    if (hash == req.headers['x-ivorypay-signature']) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event  

Responding to webhooks request

You must respond with a 200 OK status code. Any other response codes outside of the 2xx range will considered as a failure, including 3xx codes. We don't care about the response body or headers.

If we don't get a 200 OK status code, we'll retry the webhook every one minute for the next 24 hours.​

Last updated