Settlement Webhook

Overview

How it works

Useful measures include event latency, settlement-event completeness, duplicate rate, signature failures, reconciliation breaks, and time to resolve status discrepancies. Settlement Webhook is closely connected to Webhook Subscription, Reconciliation API, and At-Least-Once Delivery. Business actions triggered by Settlement Webhook should be idempotent and should verify the current object state before fulfillment or accounting updates.

What matters in practice

Settlement webhooks notify merchants about changes to a payout or settlement record. Authenticate the sending service, verify the raw payload signature and bind the event to a known settlement ID, currency, network and expected amount. Treat events as at-least-once and potentially unordered unless the provider contract explicitly says otherwise. Accounting should recognize available funds only under the merchant's settlement policy, not merely on notification receipt. Missing notifications should be recovered through periodic status queries and reconciliation against the settlement ledger.

Because merchants may miss webhook deliveries while servers are offline, an endpoint-only integration is incomplete. Implement periodic reconciliation of recent settlement IDs through a read API and alert on events without corresponding ledger movements. A signed but stale event is still authentic historical information, not necessarily the current status. The provider's contract should define how many attempts it makes and what clients must do after retry exhaustion.

If settlement notifications arrive with different event times and no sequence number, the consumer should verify current status via the provider rather than assume the latest-arriving HTTP request is the newest business event. The ledger update must also be idempotent; duplicate 'completed' notifications should not create duplicate revenue or cash postings.

Related glossary concepts

Webhook Subscription; Reconciliation API; At-Least-Once Delivery