---
title: About Events
description: >-
  Subscribe to store changes on a topic, narrow updates with triggers, and shape
  each delivery with GraphQL query and query_filter in shopify.app.toml.
source_url:
  html: 'https://shopify.dev/docs/apps/build/events'
  md: 'https://shopify.dev/docs/apps/build/events.md'
---

# About Events

**Developer preview:**

Events is in developer preview on the [`unstable`](https://shopify.dev/docs/api/usage/versioning#making-requests-to-an-api-version) API version, available today for a [subset of topics](https://shopify.dev/docs/api/events). Use it for early testing ahead of a stable release and broader topic coverage. For topics not yet supported, use webhooks alongside Events in the same `shopify.app.toml`. As Events expands topic coverage, it will become the primary subscription mechanism.

When your app needs information about specific changes that have occurred in a Shopify store, you can subscribe to Events topics as a mechanism for receiving near-real-time deliveries to cloud-based event handlers about these changes.

You declare which field changes can trigger a delivery, define GraphQL Admin queries to shape the delivered data, and optionally configure filters to modify or discard deliveries based on met conditions. The subscription carries much of the filtering that would otherwise live in your handler.

***

## What you can build

Events move customized payloads and conditional processing of deliveries into your configuration, which simplifies a number of common use cases:

* **Sync prices with less noise**: Subscribe to `product.variants.price` using [`triggers`](https://shopify.dev/docs/apps/build/events/delivery-filtering#triggers) (and similar paths your app needs). Other edits never fire a delivery if you list only the paths you care about.

  ## shopify.app.toml

  ```toml
  [[events.subscription]]
  handle = "price-sync"
  topic = "Product"
  actions = ["update"]
  triggers = ["product.variants.price"]
  ```

* **Tag products without re-syncing the catalog**: Subscribe to `product.tags` with a [`query_filter`](https://shopify.dev/docs/apps/build/events/delivery-filtering#query-filters), so tag automation runs on published products and ignores everything else.

  ## shopify.app.toml

  ```toml
  [[events.subscription]]
  handle = "tag-automation"
  topic = "Product"
  actions = ["update"]
  triggers = ["product.tags"]


  query = """
    query tags_changed($productId: ID!) {
      product(id: $productId) {
        id
        tags
        status
      }
    }
  """
  query_filter = "product.status:'ACTIVE'"
  ```

* **Include metafields with the delivery**: Include the metafields your app stores on products in your [`query`](https://shopify.dev/docs/apps/build/events/delivery-structure#custom-queries) so external IDs, mappings, and any config you've saved arrive with each change, no follow-up GraphQL Admin API call needed.

  ## shopify.app.toml

  ```toml
  [[events.subscription]]
  handle = "product-sync"
  topic = "Product"
  actions = ["update"]


  uri = "https://your-app.example.com/events"


  query = """
    query product_with_metafields($productId: ID!) {
      product(id: $productId) {
        id
        title
        metafield(namespace: "$app", key: "my_key") {
          namespace
          key
          value
        }
      }
    }
  """
  ```

***

## How it works

When a qualifying change happens in a merchant's store, Events sends a delivery. You subscribe to exactly the changes your app needs to respond to, and each delivery arrives with a JSON payload describing what changed.

You declare a subscription in `shopify.app.toml` to tell Events which resource to watch, which changes should trigger a delivery, and what data each delivery includes. Only those Events that satisfy your configured conditions (matching triggers and query filters) result in a successful delivery.

![Illustration of Events pipeline and how configuration gates deliveries.](https://shopify.dev/assets/assets/images/apps/webhooks-events/events-gates-0S8k7jvM.png)

The four core concepts are:

* **[Manage subscriptions](https://shopify.dev/docs/apps/build/events/subscribe):** Declare which resource and operations to watch, and where to send deliveries. Not all GraphQL Admin objects are supported yet. See the [Events reference](https://shopify.dev/docs/api/events) for available topics.
* **[Delivery filtering](https://shopify.dev/docs/apps/build/events/delivery-filtering):** Use `triggers` to narrow which field changes result in deliveries, and `query_filter` to suppress deliveries based on current data values.
* **[Delivery structure](https://shopify.dev/docs/apps/build/events/delivery-structure):** Shape the delivered payload with a GraphQL `query` and understand what each delivery contains.
* **[Verify deliveries](https://shopify.dev/docs/apps/build/events/verify-deliveries):** Verify HMAC signatures and ignore duplicate deliveries using `Shopify-Webhook-Id`.

***

## Next steps

[Get started with Events\
\
](https://shopify.dev/docs/apps/build/events/get-started)

[Build a working subscription and handler.](https://shopify.dev/docs/apps/build/events/get-started)

[Events reference\
\
](https://shopify.dev/docs/api/events)

[Full list of supported topics, triggers, and required scopes.](https://shopify.dev/docs/api/events)

***