Shopify webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Shopify webhooks cause in production and how to handle each one. What Shopify sends and how it's signed is on the Shopify webhooks overview, every topic is on Shopify webhook events, and signature verification code is on Verify Shopify webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx within five seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record each X-Shopify-Webhook-Id, or make processing idempotent | Drops repeats before they reach your handler |
| Ordering | Compare X-Shopify-Triggered-At or updated_at; don't rely on arrival order | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Subscribe in shopify.app.toml; reconcile from the Admin API | Accepts deliveries while your service is down and replays them |
| Choosing topics | Subscribe only to what you process; narrow with filter and include_fields | Filters and routes events by topic |
| Testing | Trigger samples with the Shopify CLI, then test real actions in a dev store | Forwards to localhost and replays past events |
| Other limits | Plan for late deliveries, compliance webhooks, version changes and API rate limits | Delivers at a rate you set, which keeps API calls from handlers within limits |
Shopify webhook timeouts and slow handlers
Return a 2xx within five seconds, then do the work in a background job.
Why it happens: Shopify has a one-second connection timeout and a five-second timeout for the whole request. Any response outside the 200 range, including a 3xx redirect, counts as an error. Handlers that write to a database or call other APIs before responding run out of time, and each failure brings a retry. Shopify treats response times between four and five seconds as a warning sign.
Fix it in your handler:
- Verify the signature and return 200 straight away.
- Push the event onto a queue and process it in a worker. Shopify recommends this for traffic bursts as well. See why to process webhooks asynchronously.
- Leave
Keep-Aliveenabled on your endpoint, because Shopify reuses connections to the same host. - Watch your 90th percentile response time on your app's Overview page in the Dev Dashboard.
With Event Gateway: Hookdeck accepts each Shopify delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take longer without failing a Shopify delivery.
Duplicate Shopify webhooks
Shopify can deliver the same webhook more than once. Make your processing idempotent, or record each X-Shopify-Webhook-Id and skip repeats.
Why it happens: Shopify says it minimizes duplicates, but a network timeout or a retry can still send a webhook again. A second subscription to the same topic also produces its own delivery, which is a common result of defining subscriptions in two places or of moving to app-specific subscriptions without removing the old shop-specific ones.
Fix it in your handler:
- Read
X-Shopify-Webhook-Idfrom the request. It's the header Shopify says to use for deduplicating individual deliveries. - Check a persistent store for that ID. If it's there, skip processing and return a success response.
- If it's new, process the delivery and save the ID.
- Don't deduplicate on
X-Shopify-Event-Id. Deliveries produced by the same merchant action share it, so use it to correlate them. - Make every handler idempotent: the same result however many times it runs.
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order Shopify webhooks
Shopify doesn't guarantee delivery order. Compare timestamps rather than relying on when a delivery arrives.
Why it happens: Shopify makes no ordering guarantee within a topic or across topics for the same resource, so a products/update webhook can arrive before products/create. A retry also lands well after newer events. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Use the
X-Shopify-Triggered-Atheader or the payload'supdated_at, as Shopify recommends, and don't let an older event overwrite newer state. - Use upserts rather than separate inserts and updates, so an update that arrives first still works.
- Write state transitions that tolerate events in any order.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Shopify webhook retries and deleted subscriptions
Shopify retries a failed delivery 8 times over 4 hours. After that it stops, and it deletes the subscription if you made it through the Admin API.
Why it happens: No response or an error counts as a failure, and the wait before the next retry grows each time. After 8 consecutive failures, Shopify deletes a shop-specific subscription and sends warning emails to your app's emergency developer address. Subscriptions in shopify.app.toml aren't deleted, but the delivery is still abandoned. Shopify's docs describe no way to resend it, and they warn that delivery isn't always guaranteed, so your app can miss events either way.
Fix it in your handler:
- Prefer app-specific subscriptions in
shopify.app.toml, which Shopify recommends and doesn't delete for failing. - For shop-specific subscriptions, run a check that lists existing subscriptions and recreates any that are missing.
- Run reconciliation jobs that fetch objects by their
updated_atsince the last run, so you stay consistent with Shopify. - Make sure someone reads the emergency developer email, and check Logs in the Dev Dashboard for removed subscriptions and deliveries that failed after retries. Shopify treats a failed delivery rate over 0.5% as high.
- After an outage, fetch the data from the outage period and feed it through your webhook processing code.
With Event Gateway: Hookdeck captures every Shopify delivery while your services are down, so Shopify's deliveries succeed and the subscription isn't deleted. Failed events can be retried automatically, manually or in bulk once you recover. See the definitive guide to Shopify webhooks over HTTPS with Hookdeck.
Choosing which Shopify topics to subscribe to
Subscribe only to the topics your integration processes, then use filter and include_fields to cut what's left.
Why it matters: A busy shop fires a lot of deliveries, and each one has to be accepted within five seconds. Each topic also needs its own access scope. The full list, with sample payloads, is on Shopify webhook events.
Fix it in your handler:
- Use
filterto suppress a delivery unless its payload matches an expression, such asstatus:active. - Use
include_fieldsto receive only the fields you need. Every field afilterrefers to must also be ininclude_fields. - Include a field that always changes, such as
updated_at. Shopify debounces identical payloads that arrive within a short window and drops the later one, so a narrow field list can hide real changes. - Use the
namefield to tell subscriptions to the same topic apart. Shopify echoes it inX-Shopify-Name. - Consider Shopify Events for field-level triggers on the topics it supports. It can run alongside webhooks.
With Event Gateway: Hookdeck filters and routes events by topic or any other property, so one Shopify subscription can feed several services.
Testing and debugging Shopify webhooks
Send sample payloads with the Shopify CLI, then test the real action in a dev store.
Why it matters: shopify app webhook trigger is the quickest check, but it has limits. Its payload never changes, failed deliveries aren't retried, and it can't validate your API webhook subscriptions.
What to do:
- Run
shopify app webhook triggerwith a topic, API version and address to check your handler. Run it against a new API version before you updateapi_version. - Update your dev store to fire real deliveries. For example, create a product to trigger
products/create. - Use a relative
urisuch as/webhooksduring development, because your tunnel URL changes each time you runshopify app dev. - Inspect individual deliveries under Logs in the Dev Dashboard, which can lag by several minutes.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events.
Other Shopify webhook limits
Plan for late deliveries, compliance webhooks, payload differences and API rate limits before they reach production.
Late deliveries. Shopify warns that webhooks can be delayed. If receiving one up to a day late would cause problems, compare its timestamp with the current time.
Compliance webhooks. Apps on the Shopify App Store must subscribe to customers/data_request, customers/redact and shop/redact, return a 401 for an invalid HMAC, acknowledge with a 2xx and complete the action within 30 days. shop/redact arrives 48 hours after a store owner uninstalls your app, and customers/redact arrives 10 days after the deletion request.
API versions. Payloads follow the version you set. When it becomes inaccessible, Shopify falls forward to the oldest accessible stable version, so read X-Shopify-API-Version rather than assuming a shape. Shopify recommends updating each quarter.
Product variants. Shopify's products/update sample carries a variant_gids list of IDs and updated_at values alongside the variants objects. Check both before you assume a payload holds everything you need, and fetch anything missing from the GraphQL Admin API. The product_feeds samples report omitted fields in metadata.truncatedFields.
Topic coverage. carts/create and carts/update only cover online store carts, not custom storefronts. audit_ is limited to one subscription per Plus store and needs Pub/Sub or EventBridge.
API rate limits. Handlers that call the Admin API for every delivery can reach its limits during a burst. See how to solve "Exceeded 2 calls per second".
With Event Gateway: Hookdeck sends one Shopify subscription's events to as many destinations as you need, absorbs spikes in its queue, and delivers at a rate you configure, which keeps API calls from handlers within Shopify's limits.
Keep an outage from deleting your Shopify subscription.
Hookdeck Event Gateway accepts every Shopify delivery straight away, verifies the signature, queues events and retries to your service on your schedule.