# 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.

Page: https://lintelagency.com/resources/graphql/webhook-subscription-with-filter

## 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.

## Facts

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

## How to use it

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

## Code

### webhook-subscription-create.graphql

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

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

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

```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"
```

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

- [Filter webhook deliveries](https://shopify.dev/docs/apps/build/webhooks/delivery-filtering)
- [webhookSubscriptionCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionCreate)

## Related

- [Reliable Shopify webhooks: retries, idempotency, ordering](https://lintelagency.com/journal/reliable-shopify-webhooks)
- [Keeping inventory in sync with another system](https://lintelagency.com/journal/sync-inventory-external-system)

License: MIT. Free to use in your own store and in client work.