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)

Payout Webhooks

Payout webhooks are fired when there is a transfer of funds.

Payout Transfer Failed

This webhook is fired when the transfer of funds is successful.

eventString

Webhook event name that indicates a successful payout transfer.

feesString or Number

Represents the fee charged for processing the payout transaction.

typeString

The nature of the transaction. Typically set to 'debit' for outgoing funds.

amountString or Number

The total amount transferred in the payout transaction.

statusString

Status of the payout operation. For successful transactions, this is usually 'success'.

channelString

The medium or route used for processing the payout. Commonly 'payout'.

referenceString

A unique identifier for tracing or reconciling the payout event.

actionString

Describes the specific type of payout action, such as 'ngn_account_payout'.

idUUID

The unique ID assigned to the payout transaction for tracking.

companyIdUUID

The UUID of the company that initiated or owns the payout transaction.

callbackUrlString

Optional URL provided for receiving asynchronous callbacks or status updates.

payout.transfer.success

Payout Transfer Failed

This webhook is fired when the transfer of funds is unsuccessful.

Note

The response is identical to that of Payout Transfer Failed. Refer to the Payout Transfer Failed section for field explanations.

payout.transfer.failed