How do I filter Shopify webhooks?

Set the filter field on the subscription, in shopify.app.toml or with webhookSubscriptionCreate. Shopify only delivers events whose payload matches it.

Why am I not receiving any webhooks after adding a filter?

A filter on a field that isn’t in the payload, or with the wrong type, silently blocks every delivery. Check the field names against a real payload of that topic.

Should I use the API or shopify.app.toml for webhooks?

For topics every store needs, shopify.app.toml is simpler: Shopify keeps the subscriptions in sync. Use the API for per-store subscriptions created at runtime.

Subscribe to a webhook with a filter

Only receive the webhooks you need: create a subscription with webhookSubscriptionCreate and a filter in Shopify search syntax, or in shopify.app.toml.

API: Admin GraphQL API
Operation: webhookSubscriptionCreate
Replaces (REST): POST /admin/api/webhooks.json
Available since: Filters: API version 2024-07
API version: 2026-10
Last checked: 2 November 2026

View as Markdown Open in ChatGPT Open in Claude

In short

To receive only some events of a topic, create the subscription with webhookSubscriptionCreate and set filter in the webhookSubscription input, using Shopify’s search syntax on payload fields, such as status:active AND variants.price:>=100. Shopify then skips deliveries where the filter is false. Apps can declare the same subscription and filter in shopify.app.toml instead, which Shopify keeps in sync on every store.

How to use it

Pick the topic and write the filter against fields of its payload; nested fields use a dot, such as variants.price.
Send SubscribeToPricedProducts with the topic, your HTTPS endpoint and the filter.
Or put the same topic, uri and filter in shopify.app.toml and deploy the app.
Verify the HMAC of every delivery and answer quickly; process the payload in a queue.

Code

webhook-subscription-create.graphql

mutation SubscribeToPricedProducts($topic: WebhookSubscriptionTopic!, $subscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $subscription) {
    webhookSubscription {
      id
      topic
      uri
      filter
      format
    }
    userErrors {
      field
      message
    }
  }
}

webhook-subscription-create.variables.json

{
  "topic": "PRODUCTS_UPDATE",
  "subscription": {
    "uri": "https://example.com/webhooks/products",
    "format": "JSON",
    "filter": "status:active AND variants.price:>=100"
  }
}

webhook-subscription-create.response.json

{
  "data": {
    "webhookSubscriptionCreate": {
      "webhookSubscription": {
        "id": "gid://shopify/WebhookSubscription/1234567890",
        "topic": "PRODUCTS_UPDATE",
        "uri": "https://example.com/webhooks/products",
        "filter": "status:active AND variants.price:>=100",
        "format": "JSON"
      },
      "userErrors": []
    }
  }
}

shopify.app.toml

# The same subscription declared in your app's configuration instead of the API.
# Deploy with `shopify app deploy`; Shopify keeps it in sync on every store.
[webhooks]
api_version = "2026-10"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "https://example.com/webhooks/products"
filter = "status:active AND variants.price:>=100"

Written by Lintel. MIT license: free to use in your own store and in client work.

Limits and edge cases

An invalid field name or type creates the subscription but suppresses every delivery. Bad syntax is rejected when you create it.
Filters are case-sensitive, and : means equality, unlike admin search.
If you also set includeFields, every field the filter uses must be in it.
metaobjects/create, update and delete topics require a filter naming the type, such as type:size_chart.
For array fields such as variants, the filter matches when any one item matches.

Questions

How do I filter Shopify webhooks?: Set the filter field on the subscription, in shopify.app.toml or with webhookSubscriptionCreate. Shopify only delivers events whose payload matches it.
Why am I not receiving any webhooks after adding a filter?: A filter on a field that isn’t in the payload, or with the wrong type, silently blocks every delivery. Check the field names against a real payload of that topic.
Should I use the API or shopify.app.toml for webhooks?: For topics every store needs, shopify.app.toml is simpler: Shopify keeps the subscriptions in sync. Use the API for per-store subscriptions created at runtime.

Shopify documentation

Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
IDs and store addresses in the examples are placeholders. Replace them with your own.
Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
MIT license. Use the code in your own store or in client work.

Need this built, tested and maintained for your store? See API integrations.