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.initiated | Transfer request was accepted and is being processed |
| transfer.completed | 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.completed Webhook 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.completed
Log and monitor failed webhooks for visibility into customer-facing delays or issues
Set up retries or alerting on webhook delivery failures
