Withdrawal Webhook

Overview

What it means in plain English

Withdrawal Webhook is an asynchronous notification that reports creation, approval, broadcast, confirmation, failure, or another defined status of a withdrawal operation. It communicates a status event but does not itself authorize the withdrawal or guarantee final receipt by the destination. A production implementation should verify the signature and source, deduplicate events, preserve withdrawal and transaction identifiers, enforce valid state transitions, reconcile against the payout ledger, and separate notification handling from authorization. The principal risks include forged success events, duplicate ledger postings, missed failures, out-of-order updates, wrong destination attribution, fulfillment before finality, and attackers using callbacks to bypass withdrawal controls.

How it works and why it matters

Withdrawal Webhook is an asynchronous notification that reports creation, approval, broadcast, confirmation, failure, or another defined status of a withdrawal operation. It communicates a status event but does not itself authorize the withdrawal or guarantee final receipt by the destination.

The principal risks include forged success events, duplicate ledger postings, missed failures, out-of-order updates, wrong destination attribution, fulfillment before finality, and attackers using callbacks to bypass withdrawal controls. Recovery for Withdrawal Webhook should combine replay controls with an authoritative status check rather than trusting delivery history alone.

A production implementation should verify the signature and source, deduplicate events, preserve withdrawal and transaction identifiers, enforce valid state transitions, reconcile against the payout ledger, and separate notification handling from authorization. A Withdrawal Webhook handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.

Useful measures include withdrawal-event latency, signature failures, duplicates, invalid state transitions, unresolved withdrawals, and webhook-to-ledger reconciliation differences. Withdrawal Webhook is closely connected to Webhook Subscription, Withdrawal State, and Payload Signature. For Withdrawal Webhook, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.

A receiver should treat transport acknowledgement and successful downstream processing as separate states for Withdrawal Webhook. The Withdrawal Webhook path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.

Business actions triggered by Withdrawal Webhook should be idempotent and should verify the current object state before fulfillment or accounting updates. Monitoring for Withdrawal Webhook should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events.

Worked example

A provider announces a withdrawal as created, processing, sent or completed. The merchant uses those notifications to update a payout dashboard, while separately recording the destination, transaction hash, chain and provider reference.

Practical checks and common confusion

Webhook status names are provider-specific. A provider's completed status may describe internal processing rather than economic finality at the destination. Verify the event authenticity and consult the payout API or chain before declaring funds irreversibly received.

Learn the related concepts

Webhook Recovery Webhook Event Log