# Shopify webhooks

Shopify webhooks are near-real-time deliveries that tell your app when a topic it subscribes to, such as `orders/create`, happens in a shop.

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

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Shopify's official docs](https://shopify.dev/docs/apps/build/webhooks/delivery-structure).

[Overview](https://hookdeck.com/webhooks/shopify) · [Webhook events (230)](https://hookdeck.com/webhooks/shopify/events) · [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/shopify/verify) · [Production guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/shopify/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Shopify-Hmac-SHA256` Format: <base64 digest> | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries) |
| Scheme | `HMAC-SHA256, base64` | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries) |
| Signed material | `{raw body}` The request body as sent, before any parsing. No timestamp is part of it. | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries) |
| How events are identified | `x-shopify-topic header` | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/delivery-structure) |
| Body format | `JSON` Content type: application/json. | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/delivery-structure) |
| API versioning | `X-Shopify-API-Version header` Seen: 2023-01, 2024-10, 2026-07. | [Shopify docs](https://shopify.dev/docs/apps/build/webhooks/subscribe) |
| Other headers | `idempotency-key, x-shopify-api-version, x-shopify-collection-id, x-shopify-customergroup-id, x-shopify-event-id, x-shopify-fulfillment-id, x-shopify-name, x-shopify-order-id, x-shopify-product-id, x-shopify-shop-domain, x-shopify-test, x-shopify-topic, x-shopify-trace-context, x-shopify-triggered-at, x-shopify-webhook-id` | [Registry record](https://hookdeck.com/webhooks/shopify.json) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill shopify-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/shopify/skill) |

[Verify Shopify webhooks](https://hookdeck.com/webhooks/shopify/verify)

## How Shopify webhooks work

Webhooks push events to your app as they happen, so you don't have to keep polling the Admin API. When a subscribed topic fires, Shopify sends the delivery to the subscription's destination: an HTTP POST with a JSON body to an HTTPS URL, or a message to Google Pub/Sub or Amazon EventBridge. Shopify recommends Pub/Sub over running your own HTTPS endpoint.

The `X-Shopify-Topic` header names the topic, and the body is the full REST resource unless you narrow it with `include_fields`. GraphQL subscriptions use enum names such as `ORDERS_CREATE`, but deliveries always say `orders/create`. `X-Shopify-API-Version` says which API version serialized the payload. You choose the version, and if it becomes inaccessible Shopify falls forward to the oldest accessible stable one.

## Setting up Shopify webhooks

- Subscribe in `shopify.app.toml` to apply to every shop that installs your app, which Shopify recommends, or per shop with the `webhookSubscriptionCreate` mutation in the GraphQL Admin API.
- Test with the Shopify CLI: `shopify app webhook trigger --topic=TOPIC --api-version=VERSION --address=URL` sends a sample payload. It doesn't test your subscription, so also perform the real action in a dev store.
- Check deliveries under Logs for your app in the Dev Dashboard. Shopify's docs describe no way to resend one, so recover missed events by fetching the data from the Admin API.
- Shopify's newer Events run alongside webhooks in the same `shopify.app.toml`, for a subset of topics. See the [Events migration guide](/webhooks/platforms/shopify-next-generation-events-migration-guide).

## Delivery behaviour

- **Timeout:** 5 seconds. for the whole request, with 1 second to connect. [Guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** 8 over 4 hours. the wait before the next retry grows after each failure. [Guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#retries)
- **After 8 failures:** subscription deleted. if it was made through the Admin API; shopify.app.toml subscriptions stay. [Guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. within a topic or across topics for the same resource. [Guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **Subscription deleted after failures.** After 8 consecutive failures, Shopify deletes a subscription made through the Admin API and warns your emergency developer email. Subscriptions in `shopify.app.toml` aren't deleted, but Shopify still stops retrying that delivery. [Retries and deleted subscriptions](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#retries)
2. **Duplicate deliveries.** Shopify can send the same webhook more than once, for example after a timeout or a retry. Deduplicate on `X-Shopify-Webhook-Id`, not `X-Shopify-Event-Id`, which separate deliveries can share. [Handle duplicates](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#duplicates)
3. **Out-of-order delivery.** Shopify doesn't guarantee order, so `products/update` can arrive before `products/create`. Compare `X-Shopify-Triggered-At` or the payload's `updated_at`. [Handle ordering](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#ordering)
4. **Deliveries can arrive late.** Shopify warns that webhooks can be delayed. If a delivery up to a day late would cause problems, compare its timestamp with the current time. [Other Shopify limits](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#other-limits)

From [Hookdeck's Shopify guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts).

## Shopify webhook best practices

- **[Verify every HTTPS delivery](https://hookdeck.com/webhooks/shopify/verify).** Without it, anyone who finds your URL can send fake events. App Store apps must return a 401 when a compliance webhook's HMAC is invalid.
- **[Respond within five seconds](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#timeouts).** Return a 2xx straight away and process the event from a queue. Anything outside the 200 range, including a redirect, counts as a failure.
- **[Deduplicate on X-Shopify-Webhook-Id](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#duplicates).** Use it, or make your processing idempotent. X-Shopify-Event-Id is shared across deliveries from the same merchant action, so it can't tell them apart.
- **[Subscribe in shopify.app.toml](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#retries).** Shopify deletes a failing subscription made through the Admin API, but not one in your app configuration file.
- **[Run reconciliation jobs](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#retries).** Shopify says not to rely on receiving every webhook. Use `updated_at` filters to fetch what changed since the last run.
- **[Narrow what you receive](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts#choosing-events).** Use `filter` to suppress deliveries and `include_fields` to shrink them, and keep `updated_at` in the list so that Shopify doesn't debounce real changes.

## Common Shopify webhook events

### Orders and customers

- [orders/create](https://hookdeck.com/webhooks/shopify/events/orders#orders%2Fcreate): New order created
- [orders/paid](https://hookdeck.com/webhooks/shopify/events/orders#orders%2Fpaid): Order is paid
- [orders/updated](https://hookdeck.com/webhooks/shopify/events/orders#orders%2Fupdated): Order details change
- [orders/cancelled](https://hookdeck.com/webhooks/shopify/events/orders#orders%2Fcancelled): Order is cancelled
- [refunds/create](https://hookdeck.com/webhooks/shopify/events/orders#refunds%2Fcreate): Refund created on an order, regardless of money movement
- [customers/create](https://hookdeck.com/webhooks/shopify/events/customers#customers%2Fcreate): New customer created
- [customers/update](https://hookdeck.com/webhooks/shopify/events/customers#customers%2Fupdate): Customer details change

### Products and inventory

- [products/create](https://hookdeck.com/webhooks/shopify/events/products#products%2Fcreate): New product created
- [products/update](https://hookdeck.com/webhooks/shopify/events/products#products%2Fupdate): Product is updated or ordered, or its variants change
- [products/delete](https://hookdeck.com/webhooks/shopify/events/products#products%2Fdelete): Product is deleted
- [inventory_levels/update](https://hookdeck.com/webhooks/shopify/events/inventory#inventory_levels%2Fupdate): Inventory level changes

### App lifecycle and compliance

- [app/uninstalled](https://hookdeck.com/webhooks/shopify/events/app#app%2Funinstalled): Shop uninstalls your app
- [customers/data_request](https://hookdeck.com/webhooks/shopify/events/customers#customers%2Fdata_request): Store owner passes on a customer's request for their data
- [customers/redact](https://hookdeck.com/webhooks/shopify/events/customers#customers%2Fredact): Store owner asks you to delete a customer's data
- [shop/redact](https://hookdeck.com/webhooks/shopify/events/other#shop%2Fredact): Shop's data due for deletion, 48 hours after uninstall

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [customers](https://hookdeck.com/webhooks/shopify/events/customers) | 26 | 26 |
| [fulfillment](https://hookdeck.com/webhooks/shopify/events/fulfillment) | 26 | 26 |
| [inventory](https://hookdeck.com/webhooks/shopify/events/inventory) | 21 | 21 |
| [products](https://hookdeck.com/webhooks/shopify/events/products) | 19 | 19 |
| [subscriptions](https://hookdeck.com/webhooks/shopify/events/subscriptions) | 18 | 18 |
| [orders](https://hookdeck.com/webhooks/shopify/events/orders) | 17 | 17 |
| [companies](https://hookdeck.com/webhooks/shopify/events/companies) | 11 | 11 |
| [returns](https://hookdeck.com/webhooks/shopify/events/returns) | 10 | 9 |
| [collections](https://hookdeck.com/webhooks/shopify/events/collections) | 9 | 9 |
| [metafields](https://hookdeck.com/webhooks/shopify/events/metafields) | 6 | 6 |

14 more resources. [All 230 events](https://hookdeck.com/webhooks/shopify/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/shopify/events): Every covered Shopify event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events): How an agent subscribes to Shopify events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/shopify/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/shopify/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill shopify-webhooks`
---

Not affiliated with Shopify. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/shopify.json) · [Report a correction](https://hookdeck.com/contact)
