Events and webhooks
Shopify offers two mechanisms for subscribing to changes to commerce resources: Events and webhooks.
Events is Shopify's next-generation subscription mechanism. It gives you field-level triggers, conditional filters, and custom GraphQL payloads. It supports precise subscriptions for specific GraphQL Admin objects, with control over what qualifies and what data arrives. You receive only the data you need, only when you need it.
Webhooks have broad coverage across all Shopify resources, with flexible delivery destinations and support for API-managed subscriptions.
Events is in developer preview on the unstable API version, available today for a subset of topics.
Use Events for early testing ahead of a stable release and broader topic coverage.
For production, use webhooks. Webhooks remain fully supported, cover all Shopify resources, and can be defined alongside Events subscriptions in the same shopify.app.toml.
Adopt Events topic by topic while keeping your existing webhook coverage in place.
As Events expands topic coverage, it will become the primary subscription mechanism, with migration guides provided for each topic.
Check the Events reference to see which topics are supported today.
Events is in developer preview on the unstable API version, available today for a subset of topics.
Use Events for early testing ahead of a stable release and broader topic coverage.
For production, use webhooks. Webhooks remain fully supported, cover all Shopify resources, and can be defined alongside Events subscriptions in the same shopify.app.toml.
Adopt Events topic by topic while keeping your existing webhook coverage in place.
As Events expands topic coverage, it will become the primary subscription mechanism, with migration guides provided for each topic.
Check the Events reference to see which topics are supported today.
How it works
The subscription workflow is the same for both Events and webhooks:
- Define a subscription: Declare a topic and where to send deliveries.
- Filter deliveries: Narrow which changes qualify.
- Receive a delivery: Shopify sends a payload when a qualifying change happens.
- Verify deliveries: Confirm the HMAC signature and deduplicate with unique IDs.
- Use the delivery: Act on the payload in your Shopify app handlers.
Where Events and webhooks diverge is in how much control you have over each stage.
Events adds field-level triggers and conditional suppression to the filter stage, and a custom GraphQL query to shape the received payload. Webhooks covers a broader set of topics, and supports shop-specific subscriptions managed through the GraphQL Admin API.
Events and webhooks can coexist in the same shopify.app.toml. Use Events for supported topics and webhooks for everything else. As topic coverage expands, migrate subscriptions one at a time.
Events and webhooks can coexist in the same shopify.app.toml. Use Events for supported topics and webhooks for everything else. As topic coverage expands, migrate subscriptions one at a time.
Events
Subscribe to topics with field-level triggers, custom GraphQL Admin API queries, and query filters. The following capabilities set Events apart from webhooks:
- Configuration:
shopify.app.tomlonly - Topic format:
topic = "Product"+actions = ["update"] - Field filtering:
triggersnarrow updates to specific field changes - Delivery filtering:
query_filterto suppress deliveries based on query results - Payload shape: Defined by your Custom GraphQL query
- Supported topics: Subset of Shopify resources while in developer preview
Define subscriptions in your app configuration file and receive deliveries only when the data you care about changes.
shopify.app.toml
[events]
api_version = "unstable"
[[events.subscription]]
handle = "my_product_events"
topic = "Product"
actions = ["update"]
triggers = ["product.variants.price"]
uri = "/events/app/products-update"
query = """
query price_change($productId: ID!, $variantsId: ID!){
productVariant(id: $variantsId) {
id
price
}
product(id: $productId) {
status
}
}
"""
query_filter = "product.status:'ACTIVE'"Response
{
"topic": "Product",
"action": "update",
"handle": "my_product_events",
"data": {
"productVariant": {
"id": "gid://shopify/ProductVariant/456",
"price": "24.99"
},
"product": {
"status": "ACTIVE"
}
},
"fields_changed": [
"product[id: 'gid://shopify/Product/123'].variants[id: 'gid://shopify/ProductVariant/456'].price"
],
"query_variables": {
"productId": "gid://shopify/Product/123",
"variantsId": "gid://shopify/ProductVariant/456"
}
}Webhooks
Subscribe to any Shopify resource using topic strings. The following capabilities set webhooks apart from Events:
- Configuration:
shopify.app.tomlor GraphQL Admin API - Topic format:
products/updatestring - Field filtering:
include_fieldstrim the payload to specific fields - Delivery filtering:
filterto suppress deliveries using search syntax - Payload shape: Fixed, REST-shaped payload
- Supported topics: All Shopify resources
Define subscriptions in your app configuration file or manage them dynamically through the GraphQL Admin API.
shopify.app.toml
[webhooks]
api_version = "2026-04"
[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products-update"
include_fields = ["id", "status", "variants.id", "variants.price"]
filter = "status:active"Response
{
"id": 9554194432293,
"status": "active",
"variants": [
{
"id": 123456789,
"price": "29.99"
}
]
}Subscribe to data on Shopify
Dive deeper with these resources to accelerate development.