🪝Webhooks

Listen to webhook events whenever certain actions occurs

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 endpoint on your server 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 type of event and the data associated with it.

Rather than continuously polling the server to check if the state has changed, webhooks provide information to you as it becomes available, which is a lot more efficient and beneficial for developers.

Here are some sample webhook payloads for deposit transactions:

{
  "id": "378b53b2-28fd-4cbd-8fe1-6786d251b7d4",
  "reference": "MBnOcItpOaP0wkBWzx",
  "senderAddress": "0x451dEFC27B45808078e875556AF06bCFdC697BA4",
  "recipientAddress": "0x062FA9157C498C8Ca4E6AF204c132EDE2500e260",
  "actualAmount": 0.51,
  "amountPaid": 0.5,
  "amountPaidFiat": 292.385,
  "fiatAmount": 300,
  "amountReceived": 0.52,
  "amountReceivedFiat": 304.0804,
  "coin": "BUSD",
  "currency": "NGN",
  "hash": "0xe929d55dde3717987191674616a0d3bbcf4b63080434b71fde41ec86aeab5fdd",
  "blockNumber": 16509617,
  "type": "received",
  "acceptPartialPayment": true,
  "status": "confirmed",
  "network": "mainnet",
  "blockchain": "Binance Smart Chain",
  "paymentLink": {},
  "paymentButton": {},
  "metadata": {},
  "customer": {
    "id": "1c4d885e-4058-45f0-8d74-ff79fe439e75",
    "name": "Abdulfatai Suleiman",
    "email": "[email protected]",
    "phone": null,
    "shippingAddress": null
  },
  "merchantAddress": "0xFdd5352384162C3342aD018AF61d77538Bdb1257",
  "feeInCrypto": 0.01,
  "fiatRate": 0.9998,
  "cryptoRate": 1,
  "createdAt": "2022-03-30 13:00:42.614077",
  "updatedAt": "2022-03-30 13:03:05.175609",
  "webhookType": "DEPOSIT_TRANSACTION"
}

Enabling webhooks

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

Here's how to set up a webhook on your Lazerpay account:

• Login to your dashboard and click on the Settings

• Navigate to the API Keys and Webhooks tab

• specify your webhook url and click on Update

When testing, you can get an instant webhook URL by visiting webhook.site. This will allow you to inspect the received payload without having to write any code or set up a server.

Validating webhooks signature

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 SHA256 hash algorithm.

In order to verify this signature came from Lazerpay, you simply have to generate the HMAC SHA256 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('sha256', secret).update(JSON.stringify(req.body), 'utf8').digest('hex');
  
    if (hash == req.headers['x-lazerpay-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, we will consider it will be 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.

Supported Webhooks types.

Here are the webhooks request types we support. We'll add more to this list as we keep adding webhook supports for different API operations in the future.

Webhook Type	Description
DEPOSIT_TRANSACTION	A deposit transaction has occurred. It could have a status of incomplete or confirmed