Handling Webhooks for Stablecoin Transfers

Bitnob uses webhooks to notify your application about key events during a stablecoin transfer’s lifecycle. Always verify the event signature before acting on a payload. This allows your backend to update transaction states in real time without polling or manually querying status endpoints.

How Webhooks Work

Once a transfer is initiated, Bitnob asynchronously tracks its status across the blockchain network. As the transaction progresses, the following events may be sent to your configured webhook URL:

event type	description
transfer.success	Transfer was successfully broadcast and confirmed
transfer.failed	Transfer failed due to an error (e.g., out of gas, revert, invalid address)

Each event payload includes the reference, chain, asset type, amount, destination address, and transaction status. The canonical payload shapes live under Webhook in the API reference, and the states a transfer passes through are listed in the withdrawal status lifecycle.

Example: transfer.success Webhook Payload

transfer.success Payload

Example: transfer.failed Webhook Payload

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

transfer.failed Payload

Webhook Configuration

To receive stablecoin transfer events, configure your webhook URL in the Bitnob Dashboard or via the API. See the webhooks overview for delivery behaviour.

Requirements:

Must be an HTTPS endpoint

Must respond with a 2xx status code within 5 seconds

Failing webhooks will be retried with exponential backoff

If you filter inbound traffic by IP, allowlist the published Source IPs

Signature Verification (Recommended)

Each webhook request is signed with a secret key. You should verify this signature to ensure the event was sent by Bitnob and hasn’t been tampered with.

X-Bitnob-Signature: sha256=5c76a3e6b7c...

You’ll receive documentation and secrets in your dashboard. Verifying signatures prevents fraudulent or spoofed events from reaching your system — working verification code is provided under Verifying Events.

Best Practices

Always verify the event field and match reference to an internal transaction — Get Transaction By ID Or Reference resolves it server-side if you need to re-check

Never credit customer balances based on transfer.initiated — only on transfer.success

Log and monitor failed webhooks for visibility into customer-facing delays or issues

Set up retries or alerting on webhook delivery failures