Checkout Webhook

Overview

A checkout webhook is a signed server notification reporting a checkout session or payment event to the merchant’s backend application. Fulfillment must use the provider-confirmed amount, currency, and final status. The webhook is more reliable than a return URL because browsers can close, lose connectivity, or be manipulated. The handler should persist the event, deduplicate by stable identifier, and update the matching order only through valid transitions. Unknown events and reconciliation mismatches should enter an exception process rather than silently completing orders. The Checkout Webhook path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state. For Checkout Webhook, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.

Merchants should verify signatures and query authoritative state when necessary. A checkout webhook informs a merchant when a hosted or embedded checkout changes state. Events may report payment detection, confirmation, expiration, failure, refund, or another lifecycle transition after the shopper’s browser has left the payment page. However, delivery remains asynchronous and may be duplicated or arrive out of order. The production contract for Checkout Webhook should state the supported event identifiers, payloads, signatures, endpoints, attempts, acknowledgements, and processing outcomes, required and optional fields, types and units, validation rules, state preconditions, version, permissions, limits, errors, and compatibility guarantees. Recovery for Checkout Webhook should combine replay controls with an authoritative status check rather than trusting delivery history alone.

Monitoring for Checkout Webhook should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events.