Skip to main content
Reliable Payment Webhooks: Prevent Duplicate Order Processing
← Back to BlogSoftware ArchitectureJuly 5, 2026

Reliable Payment Webhooks: Prevent Duplicate Order Processing

Reliable Payment Webhooks: Prevent Duplicate Order Processing

A customer pays once, but the system sends two confirmation emails or starts fulfilment twice. Another customer completes a payment and sees no order update. These failures often sit between the payment provider and the application's order workflow.

Payment webhooks deserve their own reliability plan. Receiving an event is only one step; the application still has to decide what it means, record it safely, and carry out the right business action.


Why Webhook Handling Needs Care

Stripe's webhook documentation explains that deliveries can be retried, duplicate events can occur, and event order is not guaranteed. It also recommends signature verification, asynchronous handling where appropriate, and returning a successful response promptly before complex processing.

These behaviours mean an endpoint should not assume that each incoming request represents a new business action. Delivery and processing are separate concerns.


Start With the Order Lifecycle

Write down the valid states of an order before implementing handlers. A simple model might include awaiting payment, paid, ready for fulfilment, and cancelled. Refunds may need separate records rather than a single flag that hides their history.

For every event, ask:

  • Which order does this event relate to?
  • Is this transition allowed from the current state?
  • Has the corresponding action already happened?
  • What evidence should be retained for investigation?

An event identifier helps identify a delivery, but the order's own rules decide whether fulfilment is permitted.


A Practical Processing Design

1. Check the Request

Verify the provider signature using its documented method. For Stripe, signature verification requires the raw request body. Keep this boundary separate from business logic so it is straightforward to test.

2. Record Receipt Durably

A proposed design is to store a validated event before acknowledging it, with a unique constraint for its provider event identifier. This makes concurrent deliveries easier to handle than checking an in-memory list.

If storage fails, do not report that the application has safely accepted work it cannot recover.

3. Process Through Explicit State Changes

Move the order through an allowed transition in a database transaction. A repeated event should be able to reach the same final result without creating another fulfilment task.

This property is called idempotency. It needs to cover the business effect, not just the initial HTTP request.

4. Track External Side Effects

Sending an email or creating a shipment may happen outside the database transaction. Consider a durable work record that tracks pending, completed, and failed actions. A worker can then retry a failed action without rebuilding the entire order process.

This is a design option to evaluate against the system's complexity, rather than a requirement to introduce several new services.


Test Failures Deliberately

A successful payment test is only the beginning. Build scenarios around the conditions that cause support tickets:

  • Deliver the same event twice, including concurrent requests.
  • Deliver related events in a different order.
  • Stop a worker after updating the order but before sending email.
  • Make the database temporarily unavailable.
  • Replay a failed event after the underlying problem is fixed.

For each test, define the expected final order state and the expected number of side effects. “No error was thrown” is not enough if two shipments were created.


Give Support a Recovery Path

An operations view should help an authorised person answer whether payment was confirmed, whether processing finished, and what remains pending. Keep a record of retries and manual recovery actions.

Use provider records to reconcile uncertain cases. A customer returning to a success page should not be the sole evidence used to mark an order as paid.


Final Thoughts

Reliable payment integration requires a clear order model, repeatable processing, and a way to recover incomplete work. Design for repeated and delayed messages from the start, then test the business outcome rather than only the endpoint response.


Related Blogs

  • Why Modern Software Architecture is Evolving in 2026
  • The Future of Full-Stack Development in 2026

Further Reading

Related Blogs

More blogs →