Webhook

What are webhooks?

Whenever transaction (either ON/OFF ramp) actions occur on your integration, we trigger events that your application can listen to. This is where webhooks come in. A webhook is a URL on your server where we send payloads for such events. For example, if you implement webhooks, once the on-ramp transaction is successful, we will immediately notify your server with an ONRAMP_FUFILLED event.

You can specify your webhook URL on your dashboard where we would send POST requests whenever an event occurs.

Here are some things to note when setting up a webhook URL:

1. If using .htaccess, remember to add the trailing / to the URL you set.

2. Do a test post to your URL and ensure the script gets the post body.

3. Ensure your webhook URL is publicly available (localhost URLs cannot receive events).

Receiving an event

All you have to do to receive the event is to create an unauthenticated POST route on your application. The event object is sent as JSON in the request body.

// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event
    res.send(200);
});

Verifying events

It is important to verify that events originate from Scalex to avoid delivering value based on a countefeit event. To do that: Validate the Signature - Valid events are raised with an header sx-signature which is essentially a HMAC SHA256 signature of the event payload signed using your Secret key.

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

Responding to an event

You should respond to an event with a 200 OK. We consider this an acknowledgment of your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it every 10 minutes and this will be resent 5times after which you will no longer receive any webhook notification for that transaction. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.

Supported events

On-ramp successful

{
    data: {
        notificationId,
        hash: '16eb6e74537c4bb97455dbf9c5fc783d4cc599af7a219141e1373ec4bafbee28',
        reference: '23098u908u40959',
        event: 'ONRAMP_FUFILLED',
        statusMessage: 'Token disbursed successfully'
        amount_in_fiat: 30868.24,
        amount: 52,
        currency: "NGN",
        from: 'TTmGAgfoRd5g8vKoRkFzuXs4MEvE9FvytZ', 
        to: 'TZFVNevjAjXsCcCZk2aAevm3Gni7vQN1mo',
        timestamp: 2345675434
    }
}

Off-ramp successful

On-ramp failed

Off-ramp failed