Payment Webhook Processing

Payment webhooks are HTTP POST requests that a payment gateway sends to a merchant's server to notify it of asynchronous events — authorization results, captures, refunds, disputes, and subscription renewals — without the merchant needing to poll.

The flow begins when an event occurs in the payment system (for example, a charge succeeds). The gateway constructs a JSON payload describing the event and signs it using HMAC-SHA256 with a secret shared with the merchant. The signature is sent in a request header (e.g., Stripe-Signature or X-Webhook-Signature). The gateway then delivers the POST to the merchant's configured webhook endpoint URL.

The merchant's webhook handler must process the request quickly. The first action is signature verification: extract the raw request body (before any JSON parsing, since parsing may alter byte ordering), compute the HMAC, and compare it against the header value. Any mismatch must be rejected with a 401. This prevents replay attacks and forged events. The timestamp embedded in the signature should also be checked — most implementations reject events older than five minutes.

After verification, the handler looks up the event type and dispatches it to the appropriate business logic (fulfill order, update subscription status, trigger a retry). The handler must return an HTTP 200 response promptly — ideally within 5–10 seconds — or the gateway will treat it as a failed delivery and retry. Long-running operations should be handed off to an async worker queue before returning.

If the endpoint consistently fails to acknowledge delivery, the gateway retries with exponential backoff (typically over 24–72 hours) before marking the webhook as failed and alerting the merchant. To ensure idempotency, the merchant should deduplicate incoming events by storing the event ID and skipping re-processing of already-handled IDs. The general pattern for reliable webhook delivery is covered in depth in the Webhook Delivery Flow diagram.