Payout Webhooks Now Available

Payout Webhooks Now Available

BlockBee Payouts now support webhooks. Get notified the moment a payout confirms or fails, with no polling required.

Similar to our existing payment webhooks, payout webhooks let your system react to settlement events in real time. The moment a payout confirms or fails, BlockBee pushes a signed HTTP notification to a URL you configure. No polling. No scheduled jobs. No blind spots.

What Are Payout Webhooks?

Instead of asking "has this payout settled yet?", your system gets told.

The moment a payout reaches a terminal state, BlockBee sends the full payout state to your endpoint automatically. Your system reacts instantly and moves on.

How It Works

Set up takes minutes:

1. Go to your Payout Settings in the BlockBee Dashboard
2. Enter your Webhook URL
3. Choose your preferred method: POST (default) or GET
4. Hit Send Test to validate your endpoint
5. You're live

From that point on, every settled payout triggers an automatic notification to your endpoint.

What's in the Payload

Each webhook delivers the full payout state:

• Status — machine-readable (done / error) and human-readable label
• Amounts — requested, with fee, and both converted to your fiat currency
• Fee breakdown — blockchain fee and BlockBee processing fee, separately
• Coin/ticker for the payout
• Error message if the payout failed
• Timestamp

You get everything you need to update your records in a single push.

Verified Requests

Every request carries an x-ca-signature header, an RSA signature of the request data.

Always verify the signature before acting on the payload. Our documentation includes the public key and a ready-to-use Python example so you can get verification in place quickly.

Built-In Retries

If your endpoint is unavailable or returns a non-200 status, we retry automatically.

Retries follow exponential back-off, up to 11 attempts over 3 to 4 days. No settlement event gets silently dropped.

Delivery Logs

The payout detail view in the Dashboard shows the full delivery history for every payout, every attempt, its result, and the response your endpoint returned.

Transport failures (timeouts, connection errors) show up with their own error codes so you always know exactly what happened.

Test Before You Go Live

The Send Test button on the Payout Settings page fires a one-off webhook to your configured URL using the exact same signing and payload format as a real event.

The test payload carries a sentinel ID of all zeros so your handler can recognise it and skip any database writes. Tests are rate-limited to one per minute.

Payout Webhooks are available now for all BlockBee users. Head to your Dashboard to set it up, and check the Docs for the full implementation guide.

Questions? Reach out via our contacts page.

The BlockBee Team