Handling Webhooks for Stablecoin Transfers

Bitnob uses webhooks to notify your application about key events during a stablecoin transfer’s lifecycle. 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.

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.

Requirements:

Must be an HTTPS endpoint

Must respond with a 2xx status code within 5 seconds

Failing webhooks will be retried with exponential backoff

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.

Best Practices

Always verify the event field and match reference to an internal transaction

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