Webhooks for Payouts
Bitnob provides webhook notifications to allow your systems to track the full lifecycle of a payout from payment receipt through to fiat payout delivery.
Using webhooks allows you to:
Automatically update your internal databases in real-time,
Reconcile transactions without constant polling,
Notify your end-users of payout progress.
You can optionally specify a callbackUrl at payout initiation or configure a global webhook URL at your account level.
Webhook Security
All webhook payloads are signed using HMAC SHA-256 encryption with your API secret.
You must validate webhook signatures to ensure payload integrity.
Webhooks are retried automatically with exponential backoff in case your server is unreachable.
(Webhook signature verification instructions available in the Authentication & Security section.)
Webhook Events for Payouts (Based on Your Internal Flow)
| EVENT NAME | TRIGGER |
|---|---|
payouts.asset.received | Customer's payment to the funding address/invoice has been confirmed. |
payouts.withdrawal.processing | Fiat payout to the beneficiary has been initiated. |
payouts.withdrawal.success | Payout completed successfully — funds delivered to beneficiary. |
payouts.withdrawal.failed | Payout failed after payment receipt (e.g., invalid account details, delivery failure). |
payouts.withdrawal.expired | Quote expired without receiving payment (transaction cancelled). |
payouts.withdrawal.rejected | Payout rejected for compliance or risk reasons (rare). |
Webhook Event Details
1. payouts.asset.processing
Triggered when Bitnob detects and confirms customer payment to the assigned address or invoice.
Example Payload
2. payouts.withdrawal.processing
Triggered when Bitnob has started processing the fiat payout to the recipient's bank, mobile money wallet, or cash pickup location.
Example Payload
3. payouts.withdrawal.success
Triggered when the payout has been successfully delivered to the beneficiary.
Example Payload
4. payouts.withdrawal.failed
Triggered when the payout fails after payment was received — typically due to an invalid beneficiary account, closed mobile wallet, or destination issues.
Example Payload
5. payouts.withdrawal.expired
Triggered when no payment was received within the quote validity window and the payout request is canceled.
Example Payload
5. payouts.withdrawal.rejected
Triggered when a payout is rejected after payment, due to compliance violations, risk checks, or fraud flags.
Example Payload
Webhook Delivery and Retry Behavior
Webhooks are sent via HTTPS POST to your specified callbackUrl.
Bitnob expects a 200 OK response from your server.
If your server does not respond (timeout, error), Bitnob retries delivery:
Immediate retry on first failure,
Then exponential backoff (e.g., retry after 1 min, 5 min, 15 min, 1 hour),
Up to a maximum number of attempts (e.g., 8 retries over 24 hours).
All webhook payloads are signed using your account's API secret for verification.
Best Practices for Handling Webhooks
Always verify the webhook signature before processing the payload.
Make webhook endpoints idempotent — handle duplicate notifications gracefully.
Respond quickly with 200 OK even if internal processing is delayed (use background jobs).
Log all webhook payloads for auditability and troubleshooting.
Use webhook events to proactively update your internal payout status, avoiding heavy API polling.
Summary
Bitnob’s webhook system keeps you in sync with:
Payment receipts,
Payout initiation,
Final success or failure outcomes.
Whether you're building a simple payout app or a complex merchant settlement platform, webhooks allow you to automate user updates, financial reconciliation, and operational dashboards in real-time.
The best Bitcoin-to-fiat payout systems are not just fast — they are event-driven, resilient, and transparent.
Now fully aligned with your Bitnob Offramps document
Full real webhook events, payloads, delivery behavior.
