Filter your events

Shopify provides you with a way to manage the number of event messages your app receives. Unlike payload modifications, filters are made up of rules, applied to a webhook subscription, which then act as a gate for whether or not webhooks are delivered when an event occurs.

Anchor to Example: Filtering when products are updatedExample: Filtering when products are updated

Suppose you're building an app that relies on data when a product is updated. Because of your use case, you're only interested in this data if at least one product variant's price is greater than or equal to $10.00.

However, because you've subscribed your app to the products/update webhook topic, your app receives webhooks any time the product is updated, regardless of the variant price. As a result, you receive far more webhooks than you care about, and must process them all, in order to get the information you really care about (webhooks for products where the variant price is at least $10.00).

In this case, you can use the filter capability to define a rule on your webhook subscription.

After you apply this filter, your app receives products/update webhooks for updates to products where at least one variant's price is at least $10.00.

Anchor to How to configure filtersHow to configure filters

There are two ways in which you can filter webhooks:

• In the filters argument when you create or update a subscription using your app configuration file

• With the filter input field in the webhookSubscription argument when you create or update a subscription using the GraphQL Admin API

  To determine what are valid values for your filter rules, refer to the sample payloads in the Webhooks reference.

  You denote nested fields by using a period:

name = "Example App"
client_id = "a61950a2cbd5f32876b0b55587ec7a27"
application_url = "https://www.app.example.com/"
embedded = true
handle = "example-app"

[access_scopes]
scopes = "read_products"

[access.admin]
direct_api_mode = "online"

[auth]
redirect_urls = [
  "https://app.example.com/api/auth/callback",
  "https://app.example.com/api/auth/oauth/callback",
]

[webhooks]
api_version = "2024-01"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "https://example.com/webhooks"
filter = "id:* AND status:active AND (product_type:Music OR product_type:Movies) AND -invalid_field:* AND variants.taxable:true AND variants.weight:<5 AND variants.price:>=100 AND variants.title:Album*"

[app_proxy]
url = "https://app.example.com/api/proxy"
subpath = "store-pickup"
prefix = "apps"

[pos]
embedded = false

[app_preferences]
url = "https://www.app.example.com/preferences"

[build]
automatically_update_urls_on_dev = false

mutation subscribeToWebhook {
  webhookSubscriptionCreate(
    topic: PRODUCTS_UPDATE,
    webhookSubscription: {
      uri: "https://example.com/webhooks"
      filter: "id:* AND status:active AND (product_type:Music OR product_type:Movies) AND -invalid_field:* AND variants.taxable:true AND variants.weight:<5 AND variants.price:>=100 AND variants.title:Album*"
    }
  ) {
    webhookSubscription {
      id
      createdAt
      uri
      filter
    }
    userErrors {
      field
      message
    }
  }
}

Anchor to Filtering on nested array valuesFiltering on nested array values

For fields that contain arrays of objects, you can also create filters based on the properties of those nested objects. The filter matches if at least one object in the array meets the specified condition.

For the above payload, the following filter triggers the webhook because there's at least one item in the line_items array that contains a property where name is _your_custom_property.

This means that if any line_items has at least one matching object in its properties array, the webhook is delivered.

Anchor to Differences between filters and searchDifferences between filters and search

Webhook filters leverage Shopify API's Search syntax. However, there are slight differences in the behavior between filters and search.

Anchor to Debugging filtersDebugging filters

In instances when an invalid filter is applied to a subscription, expect the following behavior:

Anchor to Required filters for metaobjects webhooksRequired filters for metaobjects webhooks

The following webhook topics require a filter to be specified:

• metaobjects/create
• metaobjects/update
• metaobjects/delete

Anchor to Filter formatFilter format

Use type:{type} where {type} is the metaobject definition's type:

To subscribe to multiple metaobject types, specify each type explicitly:

Anchor to App-owned metaobject definitionsApp-owned metaobject definitions

For app-owned metaobject definitions, use the full type value as it appears in query responses: app--{your-app-id}--{some-namespace}.

The $app:{some-namespace} shorthand isn't supported in filters.