Webhooks
Learn how to listen for transactions that happen on your account
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:
Event Type | Description |
---|---|
btc.lightning.received.success | Successfully received payment via lightning. |
btc.lightning.send.success | The lightning payment was sent successfully. |
btc.lightning.send.failed | Failed to send a lightning payment |
btc.onchain.received.success | Successfully received a Bitcoin payment on-chain |
btc.onchain.send.success | Successfully sent a payment on-chain |
btc.onchain.send.failed | Failed to make an on-chain payment |
virtualcard.transaction.debit | Debit Transactions on Virtual Cards |
virtualcard.transaction.reversed | Reversed Transactions on Debited Transactions |
virtualcard.transaction.credit | Credit Transactions on Virtual Card |
virtualcard.user.kyc.success | User successfully registered |
virtualcard.user.kyc.failed | User KYC registration failed. |
virtualcard.created.success | Virtual card created successfully |
virtualcard.created.failed | Error creating virtual card |
virtualcard.transaction.declined | Card transaction was declined by a vendor. |
checkout.received.underpaid | Checkout payment is paid but incomplete. |
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 |
mobilepayment.paid.success | Successfully paid an invoice for mobile. |
mobilepayment.settlement.failed | Settlement to Fiat failed. |
mobilepayment.settlement.success | The fiat conversion for the mobile payment was sent to the recipient Bank or Momo |
Verifying Events
Verifying that these events come from Brails is necessary to avoid creating transactions due to a fraudulent event.
To verify events, validate the x-brails-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);
});
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 the event 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 transactions, in the event that webhooks keep failing.
Testing Webhooks
Since notifications must always be available on a publicly accessible URL, you are likely to run into issues while starting to build your application in a local environment. You can easily get around this by using a tool like ngrok (opens in a new tab) or localtunnel (opens in a new tab)
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.