Webhook

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 OnRamp.Success event, the data property will hold the transaction object.

Supported Webhooks events.

Below is a growing list of Webhook events we support.

Event

onramp.success

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

onramp.failed

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

onramp.fiatPaymentReceived

This is triggered when fiat payment is received from a customer.

offramp.success

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

offramp.declined

This is only applicable to manual off-ramping. It is triggered when a manual offramp is declined. In this case, the reason for decline will be attached to the reasonForDecline property on the manual offramp response object.

offramp.cryptoPaymentReceived

This is triggered when crypto is received from a customer.

offramp.failed

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

OffRamp Webhook Events

{
    "businessId": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
    "event": "offramp.success",
    "environment": "TEST"
    "data": {
        "reference": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
        "status": "SUCCESS",
        "amount": 240000.88,
        "accountNumber": "0123890982",
        "currency": "NGN",
        "accountName": "John Doe",
        "bankName": "GT Bank",
        "transactionHash": "y7TkSOd7WD3V7YjrMDAq3d5BcgtoEQW1",
        "customer": {
            "refCode" : "KMRrEHkpDs",
            "email": "johndoe@gmail.com",
            "userId": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
            "firstName": "John",
            "lastName": "Doe",
            "context": "TEST",
            "createdAtDateOnly": "2023-04-19",
            "createdAt": "2023-04-19T06:04:34.982Z"
        }
    }
}

OnRamp Webhook Events

{
    "businessId": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
    "event": "offramp.success",
    "environment": "TEST"
    "data": {
        "reference": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
        "status": "SUCCESS",
        "token": "USDT",
        "network": "BSC_TESTNET",
        "walletAddress": "4Uv8ye8qy2DHJFmttcSeyqC8xCHq396JDTB7SKpYGFUw",
        "amount": 240000.88,
        "customer": {
            "refCode" : "KMRrEHkpDs",
            "email": "johndoe@gmail.com",
            "userId": "c13de0f2-1530-8e4e-34d4-d3c80bc1a467",
            "firstName": "John",
            "lastName": "Doe",
            "context": "TEST",
            "createdAtDateOnly": "2023-04-19",
            "createdAt": "2023-04-19T06:04:34.982Z"
        }
    }
}

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  
    }
    res.send(200);
});

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.​

PreviousFetch Single BankNextError Codes

Last updated