Filter your events
Shopify provides you with a way to you 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.
Filters are only available as of the 2024-07
version of the Admin APIs.
Anchor to Example: Filtering when products are updatedExample: Filtering when products are updated
Suppose you are building an app that relies on data when a product is updated. Because of your use case, you are only interested in this data if at least one product variant's price is greater than or equal to $10.00.
However, because you have 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.
Example filter
After you apply this filter, your app will 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 thewebhookSubscription
argument when you create or update a subscription using the GraphQL Admin APITo 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:
Example nested field
The variants
field is a top-level payload field.
If you have more than one product variant, and even one variant that has a price greater than $10.00, when the product is updated (e.g. title is changed) the webhook will fire.
Filter products/update webhooks
Filter definition
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
include_config_on_deploy = true
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 will match if at least one object in the array meets the specified condition.
Example payload with nested arrays
For the above payload, the following filter will trigger the webhook because there is at least one item in the line_items array that contains a property where name is_your_custom_property
.
Example filter for nested array values
This means that if any line_items
has at least one matching object in its properties array, the webhook will be 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.
Filters | Search |
---|---|
If you specify an invalid field, then no webhooks will be delivered. | If you specify an invalid field, then all documents are returned. |
: operator is an equality operator for Filters. | : operator does fuzzy matching when fields are tokenized. |
You must explicitly specify the fields that you want to filter on. | Term searches are supported (query:“bob” ). |
Case-sensitive. | Case-insensitive. |
Tags in some webhook topics like products/update
and orders/updated
are listed as a string. To filter products webhooks using one or several tags, treat each tag as a key word in a string, rather than a distinct value in an array.
Anchor to Debugging FiltersDebugging Filters
In instances when an invalid filter is applied to a subscription, expect the following behavior:
Scenario | Expected behavior |
---|---|
Filter uses field that doesn’t exist in payload | Filter can be created but no event messages will be sent |
include_fields , includeFields or metafieldNamespaces does not include fields that are included in the filter definition | Subscription will not be created and an error will be provided. |
Filter uses a rule that is not possible (type mismatch) | Filter can be created but no event messages will be sent. |
Incorrect filter syntax | Filter will not be created and an error message is returned. |