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 callback_url when you initialize a payout, or configure a global webhook URL at your account level.

Webhook Security

All webhook payloads are signed with an HMAC-SHA512 signature using your API secret.

You must validate webhook signatures to ensure payload integrity.

Webhooks are retried automatically if your server is unreachable.

See Verifying Events for the signature verification code.

Webhook Events for Payouts (Based on Your Internal Flow)

event name	trigger
payouts.initialized	Payout initialized against a quote and accepted for processing. Funds have not been delivered yet.
payouts.processing	Picked up by the settlement rail and on its way to the beneficiary. Not yet delivered.
payouts.withdrawal.success	Payout completed — funds have been delivered to the beneficiary.
payouts.withdrawal.expired	The payout was not completed before its quote expired. Nothing was settled — re-quote to retry.

Webhook Event Details

Note

data.status on payout webhooks is the event outcome, lowercase — initiated, processing, success, expired. It is not the payout record's lifecycle status returned by Get Payout, which is uppercase (QUOTE → INITIATED → PENDING → PROCESSING → COMPLETED / FAILED). Check the event field to decide how to handle each webhook — not data.status.

1. payouts.initialized

Triggered when the payout has been initialized against a quote and accepted for processing. Settlement has not happened yet — wait for payouts.withdrawal.success before treating the funds as delivered.

Example Payload

Payout Initialized Webhook

2. payouts.processing

Triggered when the payout has been picked up by the settlement rail and is on its way to the beneficiary. This is an in-flight update — do not treat it as delivery.

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 settlement completed. This is the event to act on when crediting an order or marking a transfer complete.

Example Payload

Payout Success Webhook

4. payouts.withdrawal.expired

Triggered when a payout was not completed before its quote expired. No funds were settled to the beneficiary — to retry, create a fresh quote and initialize again.

Example Payload

Payout Expired Webhook

Webhook Delivery and Retry Behavior

Webhooks are sent via HTTPS POST to your specified callback_url.

Bitnob expects a 200 OK response from your server.

If your server does not return a 200 (timeout, error), Bitnob retries the event 3 times after the first failure.

Because delivery can be retried, the same event may arrive more than once — de-duplicate on event_id.

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:

Payout initiation,

Successful settlement to the beneficiary,

Payouts that expired before completing.

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.