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.

Verifying Events

Verifying that these events come from Bitnob is necessary 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.

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

Note

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 or localtunnel

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.

Verify Bitnob Webhook (Node.js - Express)

Stablecoin Webhooks

Stablecoin webhooks are fired when a customer send or receive stablecoin.

Deposit stablecoin Success Webhook

eventString

The webhook event type indicating a successful stablecoin deposit. In this case, it is always 'deposit.success'.

addressString

The receiving wallet address where the deposit was sent. This belongs to the user or your system.

amountString

The deposit amount represented as a string in the smallest unit of the currency (e.g., '9000000' for 9 USDT).

chainString

The blockchain network where the deposit occurred (e.g., 'tron', 'bsc', 'ethereum').

currencyString

The currency received in the deposit, such as 'USDT', 'USDC', etc.

feeString

The fee amount associated with the deposit, typically '0' for incoming payments.

hashString

The blockchain transaction hash that uniquely identifies the deposit. Can be used to verify the transaction on a blockchain explorer.

referenceString

A unique reference generated for the deposit transaction. Useful for reconciling deposits and tracking them across logs or your system.

timestampString

The ISO 8601 timestamp of when the deposit was recorded, indicating when the transaction was detected on the blockchain.

deposit.success

Transfer Stablecoin Success Webhook

This webhook is fired when a stablecoin transfer is successfully completed on the blockchain.

Field Reference

This webhook shares the same payload structure as the Deposit stablecoin Success Webhook. See the field descriptions above for detailed explanations of each property.

transfer.success

Transfer Stablecoin Failed Webhook

This webhook is fired when a stablecoin transfer fails due to an error such as insufficient funds, invalid address, or network issues.

Field Reference

This webhook shares the same payload structure as the Deposit stablecoin Success Webhook. See the field descriptions above for detailed explanations of each property.

transfer.failed