Webhooks

Webhooks

A webhook is a URL on your server where we send payloads for transaction events. For example, if you implement webhooks, we will immediately notify your server with a btc.lightning.received.success event once a lightning payment is received.

Whenever you receive a webhook notification from us, return a 200 OK to avoid resending the same event again from our server.

Events

Transactions sent to your webhook URL have event types that provide more information about a transaction. It says what kind of transaction: sent or received and the transaction's status.

Here are the different event types:

Verifying Events

It is necessary to verify that these events come from Bitnob to avoid creating transactions due to a fraudulent event.

To verify events, validate the x-bitnob-signature header sent with the event. The HMAC SHA512 signature is the event payload signed with your secret key.

const crypto = require('crypto');
const webhookSecret = process.env.BITNOB_WEBHOOK_SECRET;
// Using Express
app.post("/webhook_url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('sha512', webhookSecret).update(JSON.stringify(req.body)).digest('hex');
    if (hash == req.headers['x-bitnob-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event  
    }
    res.send(200);
});

import hmac
from hashlib import sha512

def webhook_verification(request):
  secret = os.environ.get("BITNOB_WEBHOOK_SECRET")
  signature = request.headers.get('x-bitnob-signature')
  computed_sig = hmac.new(
    key=webhook_secret.encode("utf-8"), msg=request.body, digestmod=sha512
  ).hexdigest()
  #Bitnob generated events will return True
  return signature == computed_sig

$webhookSecret = '12345678';
$data = json_encode($_POST);
$hash = hash_hmac('sha512', $data, $webhookSecret);
if ($hash == $_SERVER['x-bitnob-signature']) {
    // Do something with event
}

Notification Retries

When posting notifications, we expect to receive a 200 response code from you. If the response code is not 200, we retry sending events 3 times after the first failure.

This way, whenever you experience downtime on your end, your updates will still be sent.

🚧

Don't rely on webhooks entirely

We recommend that you set up a service to always query transaction statuses in the events webhooks keep failing.

Testing Webhooks

Since notifications must always be available in a publicly accessible URL, you are likely to run into issues while starting to build your application in a local environment. You can easily go around this by using a tool likengrok https://ngrok.com/.

Create a tunnel, and update the new webhook URL setting on your dashboard. Only do this in your test environment to avoid leaking data to the public.