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

Agent skill: `npx skills add hookdeck/webhook-skills --skill shopify-webhooks` ([details](https://hookdeck.com/webhooks/shopify/skill))

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](/webhooks/shopify) overview, every topic is on [Shopify webhook events](/webhooks/shopify/events), and signature verification code is on [Verify Shopify webhooks](/webhooks/shopify/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return a 2xx within five seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Record each `X-Shopify-Webhook-Id`, or make processing idempotent | Drops repeats before they reach your handler |
| [Ordering](#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](#retries) | Subscribe in `shopify.app.toml`; reconcile from the Admin API | Accepts deliveries while your service is down and replays them |
| [Choosing topics](#choosing-events) | Subscribe only to what you process; narrow with `filter` and `include_fields` | Filters and routes events by topic |
| [Testing](#testing) | Trigger samples with the Shopify CLI, then test real actions in a dev store | Forwards to localhost and replays past events |
| [Other limits](#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 {#timeouts}

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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
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 {#duplicates}

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](/webhooks/platforms/shopify-embedded-app-webhook-configuration) 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](/webhooks/guides/implement-webhook-idempotency): the same result however many times it runs.

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

## Out-of-order Shopify webhooks {#ordering}

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](/webhooks/guides/webhook-ordering-why-its-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 {#retries}

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](/docs/retries) automatically, manually or in bulk once you recover. See [the definitive guide to Shopify webhooks over HTTPS with Hookdeck](/webhooks/platforms/definitive-guide-shopify-webhooks-https-hookdeck).

## Choosing which Shopify topics to subscribe to {#choosing-events}

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](https://shopify.dev/docs/api/usage/access-scopes). The full list, with sample payloads, is on [Shopify webhook events](/webhooks/shopify/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](/webhooks/platforms/shopify-next-generation-events-migration-guide) for field-level triggers on the topics it supports. It can run alongside webhooks.

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes events by topic or any other property, so one Shopify subscription can feed several services.

## Testing and debugging Shopify webhooks {#testing}

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](/docs/cli) receives webhooks on your machine without a public server, and you can replay past events.

## Other Shopify webhook limits {#other-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"](/webhooks/platforms/how-to-solve-shopify-exceeded-2-calls-per-second-for-api-client-for-webhooks).

**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.