下一代事件现已在开发者预览版中提供

下一代事件（Next Generation Events）现已提供开发者预览。事件让您能够精确控制订阅的触发时机、携带的数据内容以及每次交付的触发条件，从而解决传统 Webhook 面临的三个常见痛点：过度投递、固定负载数据以及缺乏内置的变化信号。

事件目前已可在 unstable 不稳定 API 版本上使用，涵盖产品和客户主题，更多功能将在 2026 年陆续推出。

Shopify 上的经典 Webhook

应用通常需要在 Shopify 中的商家数据发生变化时做出响应：

• 将产品数据同步到外部目录的产品信息管理应用。
• 在客户数据发生变化时更新客户档案的忠诚度应用。
• 在订单发生变化时做出响应的履约应用。

经典网络钩子通过为应用提供一种订阅主题并在资源更改时接收有效负载的方式解决了这个问题。例如，如果您的应用想知道产品何时更改，您可以订阅 products/update 主题：

[webhooks] api_version = "2026-07" [[webhooks.subscriptions]] topics = ["products/update"] uri = "/webhooks/products/update"

当产品更新时，Shopify 会向您的应用发送交付通知。您的应用会收到信号表明有更改发生，但该信号比您的应用试图运行的工作流更广泛。您的处理程序仍需要读取有效负载并判断该交付是否重要。例如，将价格同步到外部目录的应用仅对物品价格变化感兴趣。由于 products/update 网络钩子在包括标题、标签、状态和选项在内的所有产品更改时都会触发，因此应用仍需确定是否需要处理或丢弃该交付。

您可以使用 include_fields 将网络钩子有效负载减少到一定程度，但 Shopify 仍会为每个符合条件的 products/update 发送交付通知：

[[webhooks.subscriptions]] topics = ["products/update"] uri = "/webhooks/products/update" include_fields = ["id", "status", "variants.id", "variants.price", "updated_at"]

您还可以使用 filter 根据当前值抑制交付，但预定义的有效负载未描述哪个字段发生了更改，并且如果当前有效负载仍然与过滤器匹配，它也不会阻止不相关的产品更新被传递：

[[webhooks.subscriptions]] topics = ["products/update"] uri = "/webhooks/products/update" include_fields = ["id", "status", "variants.id", "variants.price", "updated_at"] filter = "status:active AND variants.price:>=10.00"

在此示例中，Shopify 会对任何处于活动状态且至少一个变体当前价格为 10.00 或以上的产品更新发送网络钩子。如果产品已经符合这些条件，则标题编辑、标签更新或选项更改仍可能通过过滤器。如果您的应用只想要价格变化，那么处理程序仍需进行额外工作：

1. 接收通过任何配置的 filter 的 products/update 交付。
2. 将当前负载与您应用存储的前一状态进行比较。
3. 丢弃那些产品仍符合筛选条件但价格未发生变化的投递。
4. 如果 Webhook 负载未包含响应所需的所有数据，请发起后续的 GraphQL Admin API 请求。
5. 在应用确认投递具有相关性后运行同步操作。

对于关注特定字段变化的工作流，检测、状态比较和后续获取都被推送到应用中处理。

介绍事件（Events）

事件保留了经典 Webhook 中有用的部分，并引入了新的配置，以定义对您的应用而言相关的内容。

与其订阅经典网络钩子主题并在事后判断交付是否重要，不如在 shopify.app.toml 中定义主题、操作、字段级触发器、有效负载形状和交付条件。主题映射到 GraphQL Admin API 对象，因此主题涵盖您希望订阅的实体及其拥有的数据。操作标准化为 create、update 和 delete，它们描述根实体的生命周期事件。例如，向产品添加变体是 Product 主题上的 update 操作；该操作告诉您产品发生了变化，而触发器和 fields_changed 告诉您内部发生了什么变化。

对于相同的价格同步工作流，请考虑以下事件订阅：

[events] api_version = "unstable" [[events.subscription]] handle = "price_sync" topic = "Product" actions = ["update"] triggers = ["product.variants.price", "product.variants.compareAtPrice"] uri = "/api/events" query = """ query priceSync($productId: ID!, $variantsId: ID!) { productVariant(id: $variantsId) { id price compareAtPrice sku } product(id: $productId) { id title status } } """ query_filter = "product.status:'ACTIVE'"

此订阅将相关性检查移至 Shopify 中的三个位置。

1. 首先，triggers 预先筛选哪些字段更改可以触发 update 交付。在这种情况下，只有当 product.variants.price 或 product.variants.compareAtPrice 发生变化时，交付才符合条件。产品标题编辑、标签更新或选项更改不符合此订阅的条件。触发器是可选的；省略它们意味着每个能够触发事件的触发器都将触发一个事件。
2. 其次，您可以使用标准的 GraphQL Admin API 查询来设计所接收的有效载荷 query。Shopify 在符合条件的更改发生后运行该查询，并将结果包含在交付的 data 字段中。在这种情况下，您的处理程序会接收到已更改变体的价格、比较价格以及 SKU，同时还有产品的标题和状态，而无需将此次交付视为发出第二次请求的信号。您无需应对固定的有效载荷架构；响应是根据您配置的使用场景生成的。如果您不需要交付中的数据，则查询是可选的，Shopify 会发送带有 fields_changed 和 query_variables 的更精简有效载荷。
3. 第三，query_filter 会抑制那些与当前查询结果不匹配的交付。在此示例中，product.status:'ACTIVE' 意味着仅当产品的当前状态为“active”时，Shopify 才会发送该交付。您在 query_filter 中使用的所有字段也必须存在于您的查询中。triggers 和 query_filter 共同作用，确保正确的交付在您调用端点之前到达您的应用。

满足这些条件后，您的应用将收到如下交付：

{ "topic": "Product", "action": "update", "handle": "price_sync", "data": { "productVariant": { "id": "gid://shopify/ProductVariant/456", "price": "24.99", "compareAtPrice": "34.99", "sku": "SIGNAL-NOT-NOISE" }, "product": { "id": "gid://shopify/Product/123", "title": "Peace & Quiet Tee", "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" } }

交付内容包括您的查询返回的 data、解释订阅触发原因的 fields_changed 路径，以及 Shopify 用于运行 GraphQL Admin API 查询的 query_variables。您的应用不再需要通过与存储的状态进行比较来推断价格是否发生变化，不再需要丢弃偶然通过当前状态过滤器的无关产品更新，也不再需要仅仅为了收集价格同步所需的数据而发起第二次请求。

开始使用

Events 目前处于开发者预览阶段，并使用 unstable API 版本。要试用 Events：

1. 升级至 Shopify CLI 版本 3.92 或更高版本。
2. 向 shopify.app.toml 添加 [events] 块。
3. 从事件参考中为支持的主题创建订阅。
4. 为您的工作流中重要的字段更改添加 triggers。
5. 添加一个 GraphQL query，并在必要时添加一个 query_filter。
6. 部署应用配置并在开发商店中测试交付。

从 Create an Events subscription 教程开始，以获取一个有效的产品同步示例，或者直接进入 migrating your existing subscriptions into Events。

下一步

随着主题覆盖范围的扩大，Events 目前处于开发者预览阶段。对于尚未支持的主题，请继续在同一个 shopify.app.toml 中将 Webhooks 与 Events 配合使用。

在测试过程中，请寻找当前由您的应用接收广泛 webhook 交付、与存储状态进行比较、在处理器中进行过滤，然后调用 GraphQL Admin API 获取更数据的流程。这些流程是事件订阅的强候选项。

如果您想了解有关开发者预览的更多背景信息，请查看 launch thread，观看 Events walkthrough，或加入 Developer Community discussion。

相关文档

• 事件参考
• 关于事件
• 创建事件订阅
• 从 webhook 迁移