Webhooks and Events

shopify app build --no-input validates shopify.app.toml without logging in. The file above was built with Shopify CLI 5.0.0 on 2026-10-27 and printed pocket-coffee-app built!. Mutated copies of the same file show which mistakes the CLI catches offline and which are left to Shopify’s servers at deploy time.

Source: Shopify: App configuration

The practical rule is that a green offline build proves the TOML syntax and a handful of enumerations, not the semantics. Topic names, trigger paths, filter fields and query complexity are checked by Shopify when the version is deployed, and shopify app deploy --no-release is the way to run those checks without publishing the change. That command needs a logged-in CLI and an app, so it was not run for this page.

include_fields lists the paths to keep. For the beans subscription, ["id", "status", "variants.id", "variants.sku", "variants.price", "updated_at"] turns a product of several kilobytes into a short document:

Source: Shopify: Webhooks delivery structure

The same option exists in the Admin API as includeFields. One side effect surprises people: when include_fields reduces the payload to a few fields, consecutive events can produce identical payloads, and Shopify debounces identical payloads that arrive within a short window, dropping the later one. A subscription to orders/updated with include_fields = ["id", "line_items.title"] would therefore swallow consecutive price changes. Always include a field that changes with every update, such as updated_at, when every update matters.

filter uses the Shopify API search syntax, with AND, OR and parentheses, and is evaluated against the payload at delivery time using current values.

Source: Shopify: Filter webhook deliveries

The filter looks like a search query but behaves differently in four ways, summarised by Shopify.

Further rules from the guide:

The key is the client secret of the app (the "API secret key"), not an access token and not a per-shop value. When the client secret is rotated, it can take up to an hour before deliveries are signed with the new secret, so a receiver that rotates secrets has to accept both for a while.

The computation is deterministic, so it can be cross-checked with any tool. With the placeholder secret placeholder-client-secret and the compliance payload of a shop/redact request as the file body.json (no trailing newline), three independent implementations print the same digest:

Output of all three (run on 2026-10-27, OpenSSL being LibreSSL 3.3.6, Node 24.21.0):

Source: Shopify: Verify webhook deliveries

The official page shows an Express handler. The version below uses only Node’s http and crypto modules so that it can run anywhere, and differs from the official snippet in one important detail: crypto.timingSafeEqual throws a RangeError when the two buffers have different lengths, so a request with a short or garbage header would crash the handler (or turn into a 500) if the lengths were not compared first.

Source: Shopify: Verify webhook deliveries

The receiver accepts both header spellings, which is how a single endpoint can serve classic webhooks and Events. It was run on 127.0.0.1 with a small driver that posts a pretty-printed order (it contains the non-ASCII character in "café") signed with the same placeholder secret. The seven scenarios and their results:

Scenario 7 is the most common real-world bug: the body is parsed with JSON.parse and written back with JSON.stringify before it is verified. The compact output has different bytes from the pretty-printed original, so the signature no longer matches even though the data is the same. The last line shows what the length guard prevents.

Source: Shopify: Verify webhook deliveries

Source: Shopify: Verify webhook deliveries

The public app template does not verify anything by hand. authenticate.webhook(request) from @shopify/shopify-app-react-router reads the raw body, validates the HMAC and the required headers, loads the offline session of the shop when one exists, and returns a typed context. Its behaviour, read from the package source (the implementation is byte-identical in versions 3.0.2, which the template installs, and 4.0.0), is:

Source: Shopify: shopify-app-js packages

The library tells classic webhooks and Events apart by the HMAC header it finds (Shopify-Hmac-Sha256 for Events, X-Shopify-Hmac-Sha256 otherwise), which is why one route can serve both. The session can be undefined after the app was uninstalled, because Shopify still delivers webhooks that were already queued. The template’s own webhooks.app.uninstalled route handles that explicitly: it deletes the shop’s sessions only when a session exists.

Because the functions throw Response objects, a route that calls authenticate.webhook needs no try block for the common failures: React Router turns the thrown response into the HTTP answer.

The handler below belongs to the Pocket Coffee app. It authenticates the request, claims the webhook id so that a duplicate is acknowledged but not processed, and logs the order. The claim is a database insert that relies on the primary key, which makes it correct under concurrent deliveries (a check followed by an insert would not be).

Source: Shopify: Webhooks delivery structure

Source: Shopify: React Router app template

The route lives next to the template’s own webhooks.app.uninstalled.tsx and webhooks.app.scopes_update.tsx; its URL /webhooks/orders/create matches the uri of the subscription. The app/scopes_update handler of the template shows another useful payload: its current array lists the scopes the app now has.

Shopify treats any answer outside the 2xx range, including a 3xx redirect, as an error. It waits one second to connect and five seconds for the whole request, and it reuses connections, so the endpoint should keep HTTP Keep-Alive enabled. The rule that follows is simple: verify, deduplicate, store the payload (or put it on a queue) and answer 200 at once; do the slow work in a worker. A compliance request that needs a database sweep, a price sync that calls another system and an order export all belong in the worker.

If Shopify gets no answer or an error, it retries eight times over the next four hours, with growing intervals. After the eight attempts it stops. A shop-specific subscription is then deleted and warning emails go to the app’s emergency developer address; an app-specific subscription is not deleted, but the deliveries that failed are lost unless the app reconciles. For a long outage:

For apps created in the Dev Dashboard or with the CLI, the app’s Overview page charts successful deliveries, the failure rate and the 90th percentile response time over a chosen range, and the Logs page lists individual deliveries of the last seven days, filterable by topic, status and shop. Each delivery shows the response code, the topic, the URI, the subscription method ("App specific" or the shop-specific subscription id), the API version, the webhook id, the response time, the attempt number and the HMAC and headers that were sent. The logs are not real time and can be delayed by several minutes. Shopify’s rules of thumb for what to fix first:

Source: Shopify: Troubleshoot webhooks

The endpoint must satisfy four rules.

Compliance topics are subscribed in the app configuration: the TOML file, or the version form of the Dev Dashboard. The Admin API cannot create them (the enum has no such values, as shown earlier). They can be sent to one endpoint with a single subscription, as the Pocket Coffee file does, or to three endpoints. The template ships them commented out under the heading "Mandatory compliance topic for public apps only"; uncomment them and replace the uri.

The Pocket Coffee app keeps a small Coffee Club note per customer, so it has something to return and to erase. The handler authenticates the delivery, stores the request with its due date (30 days after receipt) and answers at once. A nightly job (not shown) reads the unfinished rows, produces the export or performs the deletion, and sets doneAt. The webhook id is the primary key, so a redelivered request collapses into the same row.

Source: Shopify: Privacy law compliance

The route handlers were type-checked inside a copy of the official React Router template (commit of 2026-10-09, react-router typegen followed by tsc --noEmit, no errors) and executed with signed Request objects, using the placeholder secret placeholder-client-secret and a local SQLite database. The results:

The duplicate produced one stored row, not two, and the order was logged once. The forged request was rejected before the handler ran. What was not run is the part that depends on Shopify: a real compliance delivery, which cannot be triggered from a development store for customers/redact and shop/redact (they are sent after a delay), and the review that checks the endpoint.

shopify app webhook trigger sends a sample payload of any topic to an address of your choice, and it can sign it when given the client secret, which makes it the right tool for these topics. It tests the handler, not the subscription: Shopify states that triggering a webhook manually does not test that the subscription is configured correctly. See Testing deliveries.

An Events subscription has three configurable gates, evaluated in this order:

Triggers detect that something changed. The query selects what the app needs to know, independently of what changed (a change of one field can trigger a query that reads other fields). The query filter checks the state. A query filter cannot detect a transition by itself, because it sees current values and not before and after.

Source: Shopify: Manage Events subscriptions

Events require Shopify CLI 3.92 or later; the CLI used here is 5.0.0. They can be configured only in shopify.app.toml, never through the Admin API, and unsupported topics fail validation when the app is deployed.

The 2026-10 announcement lists eighteen topics: Product and Collection; Customer and Company; Order, FulfillmentOrder, Refund and Return; InventoryItem, InventoryShipment, InventoryTransfer and Location; Article, Blog and Page; and MetafieldDefinition, Metaobject and MetaobjectDefinition. Each topic has its own supported triggers, query variables and access scope (the Product topic needs read_products, Order needs one of read_orders, read_marketplace_orders, read_buyer_membership_orders or read_quick_sale, Metaobject needs read_metaobjects). The Events reference is the source of truth, and the trigger paths it lists, not the GraphQL schema, are what validation checks. Derived fields (such as product.compareAtPriceRange) and auto-updated timestamps (such as product.updatedAt) are not valid triggers because they have no independent change signal. Deprecated fields can still be valid triggers. Every trigger of a Metaobject subscription must name the metaobject type with metaobject(type: '...').

Metafield triggers arrived on 2026-07-21 for Product, Order, Customer, Collection and Location (variant metafields through the Product topic), with support for both $app-owned and ordinary metafields, subject to the app’s access to the metafield. The page on metafields and metaobjects describes the data these triggers watch.

The Coffee Club discount depends on prices, so the app wants to know when the price of a bean variant changes, but only for active products and only for variants at or above the 250 g Ethiopia price (8.90 plus 1.00 is 9.90 EUR).

Source: Shopify: Filter Events deliveries

This file (placed in the same shopify.app.toml as the webhook subscriptions above) built successfully with Shopify CLI 5.0.0. Its query was validated against the Admin 2026-10 schema as a standalone operation, and a copy with the typo prise was rejected with Cannot query field "prise" on type "ProductVariant". Did you mean "price"? (the copy no longer uses $productId, so the validator also reported that variable as unused). The query variables $productId and $variantsId are filled by Shopify: ids flow up from the changed entity through its parents, so a variant change supplies both, while a change of a product field such as the title supplies only $productId.

A subscription must therefore use only variables that every one of its triggers supplies. A subscription with the triggers product.variants.price and product.title and a query that uses $variantsId is invalid, and Shopify answers variantsId is not available in product.title. Split changes that need different variables into separate subscriptions.

For an Events delivery, the HTTP body is a JSON document with these fields.

Source: Shopify: Events delivery structure

A complete delivery of the subscription above, with Pocket Coffee values:

Source: Shopify: Events reference

The headers use the Shopify- prefix: Shopify-Topic, Shopify-Action, Shopify-Handle, Shopify-Api-Version, Shopify-Webhook-Id, Shopify-Triggered-At, Shopify-Shop-Domain and Shopify-Hmac-Sha256, and the User-Agent is Shopify-Captain-Hook. Two headers that earlier previews sent, shopify-event-id and shopify-resource-id, were removed on 2026-09-16, so a receiver must not depend on them. Verification and deduplication follow exactly the webhook rules, with Shopify-Hmac-Sha256 and Shopify-Webhook-Id; two subscriptions that match the same change produce two deliveries with different webhook ids.

Each delivery channel has a size limit: 5 MB for HTTPS, 10 MB for Google Cloud Pub/Sub and 256 KB for Amazon EventBridge. When the full content would exceed it, Shopify stores the content and sends a small body that contains only topic, action, handle, payload_url, payload_size_bytes and expires_at. fields_changed, query_variables and data are then found only in the download. Handlers have to be prepared for both shapes: check for payload_url first, verify the HMAC on the small body (not on the download), fetch the content before it expires and treat the URL as a short-lived credential. Keeping the query as small as the app needs also reduces the chance of overflow.

The route below is the Events counterpart of the orders handler. It authenticates the request with the same authenticate.webhook, deduplicates, follows payload_url when present, checks errors and then reads the variant.

Source: Shopify: Verify Events deliveries

It was run with a delivery signed with the Shopify- headers, and it printed price change PC-ETH-WHL-250: 9.90 (handle beans-price-change) and answered 200; a second delivery with the same Shopify-Webhook-Id answered 200 and printed nothing. The overflow branch was type-checked but not exercised, because it needs a download URL.

The query of an Events subscription has a complexity limit of 100 points. The limit was 250 points until the change announced on 2026-09-22. Complexity follows the GraphQL cost rules: scalars and enums cost zero, objects one point, and connections depend on first and last. The queries that Events run do not count against the app’s API rate limits. Shopify checks the complexity when an app version is created, without executing the query or waiting for an event, so shopify app deploy --no-release is the way to find out. If a query is over budget, the guidance is to split the subscription by the work it does, to query the changed child directly (the variant, using $variantsId, rather than the first 250 variants of the product), and to match each query to the variables its triggers provide. Several subscriptions for the same topic, each with its own triggers and query, are allowed.

Three different things are called events in Shopify documentation. The Events surface described here is the next generation of webhooks. The Admin API also has an Event interface (and a REST events resource) that records what happened to a resource, and on 2026-01-27 access to that data was limited to one year; this has nothing to do with Next Gen Events. Finally, the standard storefront events and the Web Pixels API are client-side analytics events. Only the first can be subscribed to from shopify.app.toml.