Custom Software & Integration

Shopify Webhooks Guide: Prevent Lost and Duplicate Orders

Share
Shopify Webhooks Guide: Prevent Lost and Duplicate Orders

How to stop lost and duplicate orders when moving Shopify orders by webhook: the five-second rule, HMAC checks, idempotency, retries and a monitoring checklist.

Most integrations that move orders from Shopify to an ERP, a shipping system or a marketplace panel rely on webhooks. If you do not understand how webhooks behave, you meet two problems: orders that go missing and orders that get recorded twice. Based on Shopify's official documentation, this article shows how to build webhooks that are secure, tolerant of repeats and easy to monitor.

What is a webhook, and why is it the backbone of order integration?

A webhook is an HTTP request Shopify sends to an address you define when something happens in the store (an order is created, a product is updated, stock changes). The alternative is for the integration to keep asking "is there a new order?". Webhooks cut delay and remove pointless queries. We covered the choice between API, webhook, file and RPA in our API integrations article; here we assume you chose webhooks and focus on making them robust.

A webhook is a notification, not a guarantee. Shopify tries to minimise repeats, but if your receiving system is down, slow or returning errors, the notification may never reach you. Your design should assume this from the start.

The five-second rule: respond first, process later

According to Shopify's documentation, your app must respond to a webhook within five seconds, and there is a separate one-second connection timeout. If no response arrives, the delivery fails. Any response other than 200, including 3XX redirects, counts as an error. That is why the documentation recommends delaying processing until after you have sent the response.

In practice the flow looks like this:

  1. The request arrives and the signature is verified.
  2. The raw payload is written to a queue or a database table.
  3. 200 is returned immediately.
  4. The real work (writing the order to the ERP, creating a shipping record) is done by a separate process reading from the queue.

Integrations that make the webhook wait for a slow ERP call time out on busy campaign days, and the problem grows at exactly the wrong moment.

A queue also gives you control over order and speed: when the target system slows down, records wait instead of disappearing, and once it recovers they are processed at a controlled pace. Returning 200 without writing to the queue creates the opposite risk, so send the response only after the record has been stored durably.

Verify the incoming request: the HMAC signature

Your address is public; anyone can post a fake order to it. That is why Shopify sends an X-Shopify-Hmac-SHA256 header with every request. It is a base64-encoded signature generated with your app's client secret and the raw request body. To verify, you compute HMAC-SHA256 over the body in the same way and compare it with the header value; you reject any delivery that does not match.

Three points to watch:

  • Verification uses the raw body. If the body is parsed to JSON and re-serialised first, the signature will not match; verify before any body-parsing middleware.
  • Compare with a timing-safe function (Shopify's Node example uses crypto.timingSafeEqual).
  • If you rotate the client secret, the documentation says it can take up to an hour before signing with the new secret begins; accepting both secrets during that window avoids transition problems.

Repeated deliveries: when the same order arrives twice

Shopify says plainly that it minimises duplicates but your app might receive the same webhook more than once, for example after a network timeout or a retry. The recommended approach is to make processing idempotent: receiving the same webhook twice must not change the outcome.

Practical ways to achieve that:

  • Use the order ID as the key: when writing to the ERP, store the Shopify order number as a unique reference; if it already exists, update the existing record instead of creating a second one.
  • Record the webhook ID: if idempotent processing is not possible, follow the documentation and store the X-Shopify-Webhook-Id header in a persistent table; if the ID was already processed, skip the work and return a success response.
  • Do not mix up the headers: with several subscriptions to the same topic, each has a different Webhook-Id but they share the same X-Shopify-Event-Id. The Event-Id is for correlating deliveries from the same merchant action, not for spotting repeats.

Hypothetical example: the cost of duplicate records

Suppose you receive 1,000 webhooks a day and 8 of them arrive twice. Without idempotency, each repeat means a second ERP record, a second shipping label or a second stock deduction. Eight duplicates a day turn into 240 correction jobs over a 30-day month (8 × 30). Once the same system uses the order number as a unique key, all 240 drop to zero. The figures are invented only to show the logic.

Retries, removed subscriptions and reconciliation

Retries and subscription removal

If a delivery fails, Shopify retries up to eight times within four hours, according to the documentation. If failures continue, the subscription is removed; the documentation says subscriptions created through the Admin API are deleted automatically after eight consecutive failures, and warning emails go to the app's emergency developer address. A removed subscription receives no deliveries until you create it again. So if your webhook address stays broken over a weekend, new orders may not arrive even after you fix the fault.

Two more retry details matter:

  • A retried webhook is delivered with the original payload from the moment it was triggered. Use the X-Shopify-Triggered-At header or a timestamp in the payload to judge whether the data is stale; a late "order updated" event, for instance, must not overwrite a newer update.
  • A retry goes to the address configured when the webhook was triggered. If you are moving to a new address, Shopify recommends keeping both addresses active for a short period during the migration.

A reconciliation job: catch what slipped through

Shopify describes as a common practice building a reconciliation job that periodically retrieves, through Shopify's APIs, the data you might have missed. For recovery after downtime it also suggests re-subscribing and fetching the data from the outage period and feeding it into your webhook processing code. The documentation does not specify which API query to use; designing that query depends on your integration.

The reconciliation job can stay simple: a few times a day, list the orders of the last few hours from the API and process those that have no counterpart in the target system. Because it uses the same processing code, idempotency already prevents duplicates. We also described using webhooks alongside periodic polling in our multichannel stock and price synchronisation article.

A monitoring and alerting checklist

Webhook failures are silent; orders pile up unnoticed. According to the documentation, a failed delivery rate above 0.5 percent is a warning sign. Set up these checks:

  1. Add an external uptime check and an error alert for your webhook address.
  2. Watch the number of records waiting in the queue and the age of the oldest one; alert when they cross a threshold.
  3. Route the app's emergency developer email to a monitored team address, not a personal inbox.
  4. Run a daily comparison: does the order count in Shopify match the count in the target system?
  5. Keep failed records in a "pending errors" table instead of deleting them, and make them reprocessable by hand.
  6. Check the subscription list regularly; are all the topics you expect still registered?

For small stores content with no-code solutions, some notification and tagging jobs can be done with Shopify Flow; but for two-way records such as ERP and shipping, the resilience rules above belong in a custom integration layer. For the decision between a ready-made integrator and a custom API, see our article on ready-made integrator or custom API.

A failure drill: test before you go live

Webhook integrations often work perfectly on a normal day and fail at the first outage. So before going live, deliberately test four scenarios:

  • Send the same event twice: in a test environment, send the same order payload twice in a row and confirm that only one record appears in the target system.
  • Send a request with a bad signature: confirm the system rejects it and creates no record.
  • Switch off the target system: cut the ERP connection on purpose; check that the webhook still responds fast, records wait in the queue and are processed when the connection returns.
  • Run the reconciliation job: delete an order from the queue on purpose and confirm the job finds and completes the gap.

These four tests take half a day and reveal most of the costliest production failures in advance. Keep the results as a short note; the team that takes over the integration will want to know what was tested.

Questions to ask when buying or commissioning an integration

If you are getting the integration from an agency or a software team, ask for written answers to these questions: Is the signature verified against the raw body? Is the response returned before processing? What happens if the same order arrives twice? After a three-day outage, how are missed orders recovered? Who receives the error alert? An integration that cannot answer these five clearly will struggle at its first test in campaign week.

Conclusion

What makes a webhook reliable is not one technical trick but four habits that complement each other: respond within five seconds and leave the work to a queue, verify the signature against the raw body, make processing tolerant of repeats, and collect what slips through with a periodic reconciliation job. Add a simple monitoring and alerting routine on top, and your order integration keeps running quietly even on campaign days.

Sources: Shopify.dev, "Verify webhook deliveries" and "Troubleshoot webhooks" pages; Shopify.dev changelog, "Updates to webhook retry mechanism" (accessed 2026). The calculation example is hypothetical.

More

Related posts