Webhook

What does it carry?

An event describing what changed: a payment was created, seen on chain, confirmed, expired, or underpaid. The exact vocabulary differs by provider and the shape does not.

It is signed. Verifying that signature before parsing anything is the first rule of handling one, and the catalogue records which providers document their event APIs, because an unsigned request arriving at your payment endpoint is not a payment event.

Why it is harder than it looks

Because the network between two servers is unreliable and neither side can distinguish the failure modes. A provider that sends an event and gets no timely response does not know whether you never received it, received it and crashed, or processed it successfully and timed out replying.

So it retries. Your handler must therefore be idempotent, keyed on the event identifier, treating a repeat as a no-op. The webhook guide covers the full set of requirements.

What it is not

A guarantee. Webhooks get lost, and a payment system that trusts them as the only source of truth will eventually mark an order unpaid that was paid.

The fix is a scheduled reconciliation pass against the provider’s API, comparing settled payments against your own records. The integration checklist treats that as part of the minimum build rather than as an optimisation.

The failure that catches people out

A handler that fulfils the order inline. It works in testing, times out under load, and the timeout looks to the provider like a failed delivery, so it retries and the load gets worse.

Acknowledge first, work afterwards. Return 200 as soon as the signature verifies and the event is recorded, then fulfil from a queue. That single change removes the class of failure where being slow is punished with more traffic.