Shopify webhooks in production: duplicates, ordering, retries and timeouts

Published · Updated

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

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 2xx within five seconds; process in a background jobAccepts the delivery at once, then queues it for your service
DuplicatesRecord each X-Shopify-Webhook-Id, or make processing idempotentDrops repeats before they reach your handler
OrderingCompare X-Shopify-Triggered-At or updated_at; don't rely on arrival orderLogs every event and attempt, so you can see arrival order when debugging
RetriesSubscribe in shopify.app.toml; reconcile from the Admin APIAccepts deliveries while your service is down and replays them
Choosing topicsSubscribe only to what you process; narrow with filter and include_fieldsFilters and routes events by topic
TestingTrigger samples with the Shopify CLI, then test real actions in a dev storeForwards to localhost and replays past events
Other limitsPlan for late deliveries, compliance webhooks, version changes and API rate limitsDelivers 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:

  1. Verify the signature and return 200 straight away.
  2. 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.
  3. Leave Keep-Alive enabled on your endpoint, because Shopify reuses connections to the same host.
  4. 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:

  1. Read X-Shopify-Webhook-Id from the request. It's the header Shopify says to use for deduplicating individual deliveries.
  2. Check a persistent store for that ID. If it's there, skip processing and return a success response.
  3. If it's new, process the delivery and save the ID.
  4. Don't deduplicate on X-Shopify-Event-Id. Deliveries produced by the same merchant action share it, so use it to correlate them.
  5. 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:

  1. Use the X-Shopify-Triggered-At header or the payload's updated_at, as Shopify recommends, and don't let an older event overwrite newer state.
  2. Use upserts rather than separate inserts and updates, so an update that arrives first still works.
  3. 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:

  1. Prefer app-specific subscriptions in shopify.app.toml, which Shopify recommends and doesn't delete for failing.
  2. For shop-specific subscriptions, run a check that lists existing subscriptions and recreates any that are missing.
  3. Run reconciliation jobs that fetch objects by their updated_at since the last run, so you stay consistent with Shopify.
  4. 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.
  5. 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:

  1. Use filter to suppress a delivery unless its payload matches an expression, such as status:active.
  2. Use include_fields to receive only the fields you need. Every field a filter refers to must also be in include_fields.
  3. 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.
  4. Use the name field to tell subscriptions to the same topic apart. Shopify echoes it in X-Shopify-Name.
  5. 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:

  1. Run shopify app webhook trigger with a topic, API version and address to check your handler. Run it against a new API version before you update api_version.
  2. Update your dev store to fire real deliveries. For example, create a product to trigger products/create.
  3. Use a relative uri such as /webhooks during development, because your tunnel URL changes each time you run shopify app dev.
  4. 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_events/admin_api_activity 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.

Not affiliated with Shopify. Facts are compiled from public sources and linked inline.