Webhooks

Learn how to listen for transactions that happen on your account

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 status of the transaction.

Here are the different event types:

Event Type

Description

btc.lightning.received.success

Successfully received payment via lightning

btc.lightning.send.success

Lightning payment sent successfully

btc.lightning.send.failed

Failed to send a lightning payment

btc.onchain.received.success

Successfully received a bitcoin payment onchain

btc.onchain.send.success

Successfully sent a payment onchain

btc.onchain.send.failed

Failed to make an onchain payment

virtualcard.transaction.debit

Debit Transactions on Virtual Cards

virtualcard.transaction.reversed

Reversed Transactions on Debit Card

checkout.received.underpaid

Checkout payment paid but incompleted

checkout.received.paid

Checkout payment completed.

stablecoin.usdc.received.success

USDC received successfully

stablecoin.usdc.send.success

USDC sent successfully

stablecoin.usdc.send.failed

USDC sending failed

stablecoin.usdt.received.success

USDT received successfully

stablecoin.usdt.send.success

USDT sent successfully

stablecoin.usdt.send.failed

USDT sending failed

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

Notification Retries

When posting notifications, we expect to receive a 200 response code from you. If the response code is not 200, we will retry the notification every 30 minutes for up to 4 days.

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 like ngrok https://ngrok.com/.

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


Did this page help you?