Payout Webhook

Definition

Payout Webhook is an asynchronous integration concept that delivers asynchronous provider events to a configured endpoint when an outbound transfer’s state or transaction evidence changes.

Overview

Contents Hide

Context and purpose
How it works
Practical checks and failure points
Related concepts

Context and purpose

A webhook may also precede final blockchain confidence even when a provider calls the transfer completed. Duplicate, delayed, forged, or out-of-order events can create incorrect recipient balances or repeated notifications. Receivers should verify authenticity, validate payout identity and material fields, deduplicate atomically, and enforce legal state transitions. Events may report processing, completion, rejection, cancellation, transaction hash creation, or another provider-defined transition and can update recipient, support, or ledger systems. Replay of Payout Webhook should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event. The Payout Webhook path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state. A Payout Webhook handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response. Business actions triggered by Payout Webhook should be idempotent and should verify the current object state before fulfillment or accounting updates.

How it works

A payout webhook reports changes to an outgoing transfer such as accepted, processing, broadcast, completed or failed, according to the provider’s vocabulary. It must be interpreted with the specific payout ID.

Practical checks and failure points

Verify signature, check account ownership, support out-of-order events and reconcile destination transaction evidence.

Payout Retry · Duplicate Payout

Example

An API accepts payout P-102, and its webhook later reports broadcast followed by confirmed. Booking the payout as complete on the first message would be premature.

Comparison

Outgoing payout events differ from incoming customer payment notifications.

Key Takeaway