Prevent duplicate webhook-created orders by making order processing idempotent: repeated delivery of the same event must not repeat the business action. Store a durable event identifier, enforce uniqueness in the database, and define what happens when work succeeds but the acknowledgment fails. The right design depends on the sender’s retry behavior and on where order data is written.
A webhook retry can be normal; a second order is not
An integration should treat a webhook as a message that may arrive more than once, not as a guaranteed one-time command. To prevent duplicate orders, record each event durably and make the business operation safe to repeat. If the same event is delivered again, the system should recognize it and avoid creating another order.
This matters because senders commonly retry after a timeout or an unsuccessful response. The receiver may have completed the work even though its reply never reached the sender. A retry is then indistinguishable from a new attempt unless the receiver has stored enough information to tell them apart.
Use two checks: event identity and order identity
First, use the sender’s stable event identifier, when available, to recognize a repeated delivery. Store it in a table with a unique database constraint. A unique constraint is a database rule that prevents two rows from claiming the same identifier, even if two requests arrive at nearly the same time.
Second, identify the business object the event concerns. For example, an order-placed event may have an order ID or checkout reference. This second check can protect against a sender generating a new event ID for the same underlying action. Choose keys that reflect the actual process: a customer ID alone is generally not enough, since one customer can place multiple orders.
Make receipt and order creation recoverable
A common implementation stores the event receipt and creates or updates the order in one database transaction. If the order write fails, the transaction can roll back the receipt too, leaving a retry able to try again. If the receipt is permanently marked complete before the order is safely written, a crash in between can cause the order to be lost instead.
Some workflows need a processing state because the event triggers work outside the database, such as calling a fulfillment service. In that case, record states such as received, processing, completed, and failed, plus timestamps and a retry policy. The state model should distinguish a transient failure from a permanent rejection and give operators a way to inspect or safely resume stuck work.
Return responses that match what actually happened
Define response behavior for each outcome. A newly accepted event should receive the success response expected by the sender. A recognized duplicate can usually receive a successful acknowledgment too, because the receiver has already handled it; returning an error may prompt needless retries. Invalid data should not be silently accepted, while a temporary internal failure should be reported in a way that permits a retry if the sender supports one.
Exact response codes and retry timing depend on the sending platform, so confirm its current delivery rules before implementation. Do not assume every sender retries the same errors or for the same duration. Also authenticate incoming requests, validate required fields and allowed values, and reject malformed payloads before they can affect order data.
Test the awkward timing, not just the happy path
A basic test that posts one event and sees one order is not enough. Send the identical event twice, then simulate two copies arriving concurrently. Confirm the database constraint or equivalent locking behavior prevents a race from producing two orders. Test a timeout after the order is committed but before the sender receives the response, then resend the event and verify the existing order is returned or left unchanged.
Also test partial failures: the database becomes unavailable, a required field is missing, or a downstream fulfillment call fails after order creation. Decide which failures should be retried and which need staff review. Logs should connect the event ID to the order ID and processing outcome, while avoiding unnecessary sensitive payload data.
When a separate deduplication system is unnecessary
A small integration may not need a message broker or a separate event-processing platform. If the application already has a reliable database, a unique event record, an appropriate transaction, and a clear recovery path may be sufficient. Extra infrastructure adds operational work and is not a substitute for deciding what counts as the same order.
A practical next step is to map the sender’s event identifier, the order’s business key, and each point where processing can fail. Then review the sender’s delivery and retry behavior and test those cases against a non-production environment. If the workflow spans multiple services or cannot keep its state changes in one transaction, scope the recovery and reconciliation design before adding volume.
Before you ship webhook order processing
- Identify the event identifier and the business-level key that defines one order.
- Persist event receipt and order creation in a transaction or with an equivalent recovery plan.
- Define what the sender should receive when an event is new, duplicated, invalid, or temporarily unprocessable.
- Test simultaneous duplicate deliveries, timeouts, and retries after partial failure.
- Log event IDs and outcomes without exposing unnecessary customer or payment data.
Questions about this approach
What does idempotent mean for an order webhook?
An idempotent operation can be repeated without repeating its intended effect. In this context, another delivery of an event should not create another order. The system can still update status or record that a duplicate arrived, if that is part of the workflow.
Do we need a message queue to stop duplicate orders?
Not necessarily. A durable event table with a unique identifier and a database transaction can be enough for a straightforward workflow. Consider a queue or broker when work must be processed asynchronously, buffered during downtime, or coordinated across services, but design duplicate protection and recovery either way.
How can we test retries without placing real orders?
Use a controlled test environment and simulate repeated and concurrent deliveries, timeouts, and failures at different processing stages. Check the sender’s current retry rules and ensure tests cannot create real orders, trigger fulfillment, or send customer notifications.
For help applying this approach, explore our API integration and custom programming services.
Discuss your project with Full Blown Studio
Tell us what needs to work better and what you have tried. Discuss your project, email bob@fullblown.com, or call (661) 429-0940.
