Payment Webhook Replay Protection: Hardening the Receiving Boundary

Header image: conceptual illustration.

A webhook endpoint is deliberately reachable by an external provider. That does not make every request to it trustworthy. The receiving boundary must reject forged or malformed messages, recognize legitimate retries and avoid acknowledging work that will be lost.

This guide focuses on replay and receiving-boundary controls. The general webhook guide explains how notifications fit into payment processing.

Use the provider's actual verification protocol

There is no universal signature header or algorithm shared by all gateways. Read the documented payload format, signature or validation mechanism, account scope and environment rules. Prefer the supported verification library when one exists.

Stripe requires the raw request body for its signature verification. Middleware that changes JSON formatting before verification can break the signature. Its signing secret belongs to the endpoint and environment; it is not the same as an API credential.

SSLCommerz's documentation describes a different verification flow and requires transaction and amount validation using its Order Validation API. Do not copy a Stripe header check into a different provider integration and declare it secured.

Replay protection is distinct from event deduplication

A captured valid request can be replayed maliciously. For Stripe, the signed delivery timestamp and verifier tolerance address recency. Stripe warns that a tolerance value of zero disables the recency check. Keep clock synchronization and the supported verification behavior intact.

A legitimate provider retry can be delivered with a new signature and timestamp while still describing the same event. Event-identifier deduplication recognizes that repeated delivery. A financial-effect uniqueness control ensures that even different events describing one payment cannot double-credit it.

Do not build replay handling around rejecting every old business event. A delayed or recovered event can legitimately concern an older payment. Delivery authentication, event identity and business-resource state solve separate problems.

Bound what the receiver accepts

Accept the documented method and content type. Apply reasonable payload-size and parsing limits compatible with the provider. Avoid reflecting raw request content in errors. Configure network controls according to the provider's published requirements and validate any maintained allowlist; an outdated rule can block legitimate delivery.

Do not trust a callback URL supplied in an untrusted payload and fetch it arbitrarily. If the processing path retrieves a resource, construct the request using the known provider API and validated identifiers. This keeps an attacker from turning a notification into an unrelated network request.

Exemptions from browser-oriented protections should be narrow. A webhook may not carry a browser session or CSRF token, but that is not a reason to disable authentication across the entire site.

Acknowledge durable receipt, not imagined completion

After successful verification, save or enqueue the event durably before acknowledging it. Return the provider's expected success response promptly, then process complex work asynchronously if the architecture supports that pattern.

Stripe recommends quickly returning a successful response and handling events asynchronously. If the queue is unavailable and the event is not durably stored, reporting success can permanently lose the notification. Conversely, financial processing should remain idempotent because the provider may retry after a transient receiver failure.

A receiver acknowledgment is not a customer payment confirmation. Verify successful final provider status, merchant/order reference, amount and currency before any idempotent credit.

Worked hypothetical replay test

Invented example: A test receiver accepts a valid notification and records DEMO-EVENT-1. A second delivery of that event has a valid fresh provider signature. It is acknowledged but produces no second financial effect.

A captured delivery with a stale signed timestamp fails the provider's recency check. A message with altered amount fails signature verification or subsequent authoritative amount validation. A forged request with a plausible order reference never reaches the financial worker.

The logs retain safe reason categories and event identities. They do not store full raw payloads, secret headers or customer identity media to demonstrate that protection worked.

Hardening test checklist

• Valid delivery succeeds in the correct environment.
• Wrong secret, altered body and missing verification data are rejected.
• Provider-supported timestamp checks distinguish stale delivery from legitimate retry.
• Duplicate events and duplicate financial effects are independently prevented.
• Queue failure cannot be reported as durable success.
• Size limits and malformed input cannot overwhelm parsing.
• Outbound lookups target only the intended provider API.
• Logs exclude credentials and unnecessary personal data.

The payment security guide supplies broader access and monitoring context.

Frequently asked questions

Is a valid signature enough to credit an order?

No. It establishes origin and integrity under the verification scheme, not the complete merchant, order, final-status and amount checks.

Should every invalid request receive a success response to stop retries?

Follow the provider's documented protocol. Do not treat invalid or undurably stored work as successfully processed merely to hide delivery errors.