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.
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.
Key facts
{raw body} The request body as sent, before any parsing. No timestamp is part of it.
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 Setting up Shopify webhooks
- Subscribe in
shopify.app.tomlto apply to every shop that installs your app, which Shopify recommends, or per shop with thewebhookSubscriptionCreatemutation in the GraphQL Admin API. - Test with the Shopify CLI:
shopify app webhook trigger --topic=TOPIC --api-version=VERSION --address=URLsends 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.
Delivery behaviour
5 seconds for the whole request, with 1 second to connect Retries 8 over 4 hours the wait before the next retry grows after each failure After 8 failures subscription deleted if it was made through the Admin API; shopify.app.toml subscriptions stay Ordering not guaranteed within a topic or across topics for the same resource Known failure modes
From Hookdeck's Shopify guide →-
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
Retries and deleted subscriptions →shopify.app.tomlaren't deleted, but Shopify still stops retrying that delivery. -
Duplicate deliveries
Shopify can send the same webhook more than once, for example after a timeout or a retry. Deduplicate on
Handle duplicates →X-Shopify-Webhook-Id, notX-Shopify-Event-Id, which separate deliveries can share. -
Out-of-order delivery
Shopify doesn't guarantee order, so
Handle ordering →products/updatecan arrive beforeproducts/create. CompareX-Shopify-Triggered-Ator the payload'supdated_at. -
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 →
Shopify webhook best practices
- Verify every HTTPS delivery. 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. 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. 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. Shopify deletes a failing subscription made through the Admin API, but not one in your app configuration file.
- Run reconciliation jobs.
Shopify says not to rely on receiving every webhook. Use
updated_atfilters to fetch what changed since the last run. - Narrow what you receive.
Use
filterto suppress deliveries andinclude_fieldsto shrink them, and keepupdated_atin the list so that Shopify doesn't debounce real changes.
Common Shopify webhook events
Orders and customers
orders/create | New order created |
orders/paid | Order is paid |
orders/updated | Order details change |
orders/cancelled | Order is cancelled |
refunds/create | Refund created on an order, regardless of money movement |
customers/create | New customer created |
customers/update | Customer details change |
Products and inventory
products/create | New product created |
products/update | Product is updated or ordered, or its variants change |
products/delete | Product is deleted |
inventory_levels/update | Inventory level changes |
App lifecycle and compliance
app/uninstalled | Shop uninstalls your app |
customers/data_request | Store owner passes on a customer's request for their data |
customers/redact | Store owner asks you to delete a customer's data |
shop/redact | Shop's data due for deletion, 48 hours after uninstall |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
customers | 26 | 26 |
fulfillment | 26 | 26 |
inventory | 21 | 21 |
products | 19 | 19 |
subscriptions | 18 | 18 |
orders | 17 | 17 |
companies | 11 | 11 |
returns | 10 | 9 |
collections | 9 | 9 |
metafields | 6 | 6 |
14 more resources, including Other Shopify events. All 230 events →
In this hub
| Webhook events → | Every covered Shopify event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Shopify events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill shopify-webhooks |
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.