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.initialized	Payout request accepted and quote is being acted on. The payout is now awaiting processing.
payouts.processing	Funds are being converted and sent to the beneficiary's bank, mobile money wallet, or cash pickup.
payouts.withdrawal.success	Payout completed — funds have been delivered to the beneficiary.
payouts.withdrawal.failed	Payout failed after initiation — check failure_reason for details (e.g., invalid account, closed wallet).
payouts.withdrawal.expired	Quote validity window expired before payout could be completed. Transaction is automatically cancelled.

Webhook Event Details

1. payouts.initialized

Triggered when a payout has been initialized and is awaiting processing. This confirms the payout request was accepted and the quote is being acted on.

Example Payload

Payout Initialized Webhook

2. payouts.processing

Triggered when Bitnob is actively processing the payout — funds are being converted and sent to the beneficiary's bank, mobile money wallet, or cash pickup location.

Example Payload

Payout Processing Webhook

3. payouts.withdrawal.success

Triggered when the payout has been successfully delivered to the beneficiary. The completed_at field indicates when the funds were received.

Example Payload

Payout Success Webhook

4. payouts.withdrawal.failed

Triggered when the payout fails after initiation — typically due to an invalid beneficiary account, closed mobile wallet, or destination issues. Check the failure_reason field for details.

Example Payload

Payout Failed Webhook

5. payouts.withdrawal.expired

Triggered when the quote validity window expires before the payout could be completed. The transaction is automatically cancelled.

Example Payload

Payout Expired Webhook

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.