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.

230 events covered 31 captured samples

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

Signature header
X-Shopify-Hmac-SHA256

Format: <base64 digest>

Scheme
HMAC-SHA256, base64
Signed material
{raw body}

The request body as sent, before any parsing. No timestamp is part of it.

How events are identified
x-shopify-topic header
Body format
JSON

Content type: application/json.

API versioning
X-Shopify-API-Version header

Seen: 2023-01, 2024-10, 2026-07.

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
Agent skill
npx skills add hookdeck/webhook-skills --skill shopify-webhooks

Verify Shopify webhooks →

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.

Delivery behaviour

  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 →
  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 →
  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 →
  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 →

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_at filters to fetch what changed since the last run.
  • Narrow what you receive. 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 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

customers/create · /update · customer_account_settings/update · customer_groups/create +22

26 26
fulfillment

fulfillment_events/create · _events/delete · _holds/added · _holds/released +22

26 26
inventory

inventory_items/create · _items/delete · _items/update · _levels/connect +17

21 21
products

products/create · /update · /delete · product_feeds/create +15

19 19
subscriptions

selling_plan_groups/create · selling_plan_groups/delete · selling_plan_groups/update · subscription_billing_attempts/challenged +14

18 18
orders

orders/create · /updated · /paid · /cancelled +13

17 17
companies

companies/create · /delete · /update · company_contact_roles/assign +7

11 11
returns

returns/approve · /cancel · /close · /decline +6

10 9
collections

collection_listings/add · collection_listings/remove · collection_listings/update · collection_publications/create +5

9 9
metafields

metafield_definitions/create · metafield_definitions/delete · metafield_definitions/update · metaobjects/create +2

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.

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