Updates to Events payloads and subscription configuration

Starting today, we're updating Events payloads, trigger syntax, and delivery headers. Classic Webhook subscriptions are unaffected.

What's changed

fields_changed now describes how each path changed

The flat array becomes an object containing three arrays: added, updated, and removed.

Developers can distinguish a resource or relationship being added, a value being updated, or a resource or relationship being removed without querying just to infer what happened.

Update payload handling to read fields_changed.added, fields_changed.updated, and fields_changed.removed. Adding a variant to a Product, for example, keeps the Product's action as update and places the variant path in fields_changed.added.

Before:

{
   "topic": "Product",
   "action": "update",
   "fields_changed": [
     "product[id: 'gid://shopify/Product/123'].variants[id: 'gid://shopify/ProductVariant/456']"
   ]
}

After:

{
   "topic": "Product",
   "action": "update",
   "fields_changed": {
      "added": [
        "product[id: 'gid://shopify/Product/123'].variants[id: 'gid://shopify/ProductVariant/456']"
      ],
      "updated": [],
      "removed": []
   }
}

Parent triggers use an explicit wildcard

To subscribe to all supported fields below a parent path, use a terminal .*, such as triggers = ["product.variants.*"].

Leaf triggers such as product.variants.price remain unchanged. Existing subscriptions continue to work, but you must update parent triggers to the new syntax the next time you deploy shopify.app.toml. The syntax change preserves matching behavior and event volume for equivalent subscriptions.

Before:

triggers = [
    "product.variants",
    "product.options.optionValues.swatch"
 ]

After:

triggers = [
    "product.variants.*",
    "product.options.optionValues.swatch.*"
]

Two redundant delivery headers are removed

Events deliveries no longer include shopify-event-id or shopify-resource-id.

Update your Shopify API packages to their latest versions, which handle this change. If your own code reads these headers or requires them for validation, remove that dependency.

triggers are now required

Event subscriptions with the update action require at least one trigger to be present. Existing subscriptions will continue to work as expected.

What to do

Review the migration steps and examples in the community post, and share any questions or feedback in the thread.