Webhook
A webhook is a call the payment provider makes to a URL the merchant registered whenever an event occurs — a payment succeeded or failed asynchronously, a dispute opened, a payout sent, a subscription renewed — carrying the event's data so the merchant's system can act without polling. It is how an integration learns what happened after the API call returned, and the part most often built badly.
- Also known as
- Payment webhook, Event notification, Callback
- Used at
- every modern PSP and payments API — asynchronous payment methods (bank transfers, wallets, BNPL) that complete after the checkout, disputes, payouts, account status changes, fraud alerts
- Binding
- an integration contract — the provider promises delivery attempts with retries over hours or days; the merchant must acknowledge with a 2xx response, verify the signature, and process events idempotently
- Typical mechanics
- an HTTPS POST with a JSON payload and a signature header (an HMAC over the body with a shared secret); retries on non-2xx responses with exponential backoff; an event ID for deduplication; a dashboard to replay missed events
- Typical failures
- unsigned endpoints that accept forged events ("payment succeeded" from anyone); handlers that time out and cause retries, then process twice; endpoints down during a deploy, events retried and then expired; order state updated from webhooks in the wrong sequence
- Parties
- the provider that sends, the merchant's server that receives, and the systems downstream that act on it — fulfilment, accounting, customer notifications
How a webhook works in practice
A customer pays by bank transfer. The checkout shows "pending" and the API call returns before the money moves. Hours later the transfer arrives; the PSP creates a `payment.succeeded` event and POSTs it to the merchant's webhook URL, signed. The merchant's endpoint verifies the signature against its secret, checks the event ID against those already processed, updates the order to paid, triggers fulfilment, and returns 200. If the endpoint was down, the PSP retries — in a minute, five minutes, an hour, up to a day or more — until it gets a 200 or gives up, at which point the event is in the dashboard for replay. The merchant learned about the payment without asking; the alternative, polling every payment's status every minute, does not scale.
The engineering rules are few and violated often. Verify the signature, or anyone can mark an order paid. Respond quickly and process asynchronously, or slow handlers cause timeouts and duplicate deliveries. Deduplicate by event ID, because at-least-once delivery means twice sometimes. Do not trust event order; fetch the object's current state from the API if the sequence matters. And reconcile: webhooks are a notification, not the ledger, and a daily comparison of the provider's records with the merchant's finds the ones that were missed.
For a payments company the webhook infrastructure — delivery guarantees, retries, replay, signing — is a product surface merchants judge; for a merchant's engineers, it is the integration's hardest 10%.
Example
A retailer's webhook endpoint accepts unsigned events and updates orders synchronously in the handler. Two problems arrive in one month. A fraudster who read the API documentation posts a forged `payment.succeeded` for a €2,400 order, which ships. And a deploy takes the endpoint down for eleven minutes at peak; the PSP retries 3,000 events over the next hour into a handler that, now slow under the backlog, times out and is retried again — 400 orders are marked paid twice and 60 customers receive two confirmation emails and, in nine cases, two parcels. The rebuild: signature verification, a queue that acknowledges at once and processes behind, deduplication by event ID, and a nightly reconciliation against the PSP's API. The next deploy at peak loses nothing; the forged event is rejected in a millisecond.
Common mistakes
- Unverified webhooks that trust whatever arrives. - Handlers that do the work before responding, so the provider times out and retries. - No deduplication, so at-least-once delivery becomes at-least-twice processing. - Assuming events arrive in order. - Treating webhooks as the source of truth and never reconciling against the provider's records.