随着 2026-10 2026-10 API 版本 Next Gen Events（Shopify 经典 Webhook 的继任者）现已全面可用。Events 比经典 Webhook 提供了更多的自定义选项，允许您选择应用接收哪些变更以及有效载荷中包含哪些数据。
例如，如果您的应用跟踪集合成员资格，那么得知集合发生更改只是工作的一部分。您仍然需要知道哪些产品加入或离开了该集合。使用经典 Webhook，这可能意味着获取集合中的产品、将其与您保存的列表进行比较，然后更新您的应用。为了识别一次变更，您需要完成所有这些工作。
我们构建 Events 是为了简化这一过程。您的订阅会告知我们您的应用关心哪些变更以及处理这些变更所需的数据。我们将变更、受影响的资源 ID 以及您的 GraphQL 查询结果一起发送给您。
告诉我们您的应用关心什么
您可以在应用的 shopify.app.toml 配置文件 中直接配置 Events 订阅。一个事件包含三个组成部分：
- triggers：哪些变更对您的应用至关重要。例如，产品加入或离开某个集合，或者变体价格发生变化。
- query：发生该变更时您需要哪些数据。编写一个 GraphQL Admin API 查询，我们将把其结果包含在负载中。您还可以包含相关数据和元字段。
- query_filter：您的应用需要接收哪些结果。例如，您可以将交付限制为仅具有 ACTIVE 状态的产品。
触发器和查询是相互独立的。对一个字段的更改可以触发一个查询，以获取应用所需的其他数据。然后查询过滤器会检查结果以决定是否交付。有关触发器、查询和查询过滤器如何协同工作的更多信息，请参阅 Events 概述。
同时接收变更和您所需的数据
让我们继续使用集合成员资格作为示例。您的应用维护着一个搜索索引，每当有产品加入或离开某个集合时，您都需要更新它。
您可以订阅 collection.products 并在查询中直接使用集合和产品 ID：
[events] api_version = "2026-10" [[events.subscription]] handle = "collection-membership" topic = "Collection" actions = ["update"] triggers = ["collection.products"] uri = "/api/events/collections" query = """ query CollectionMembership($collectionId: ID!, $productsId: ID!) { collection(id: $collectionId) { id hasProduct(id: $productsId) } } """当产品 456 添加到集合 123 时，您将收到如下负载：
{ "topic": "Collection", "action": "update", "handle": "collection-membership", "data": { "collection": { "id": "gid://shopify/Collection/123", "hasProduct": true } }, "fields_changed": { "added": [ "collection[id: 'gid://shopify/Collection/123'].products[id: 'gid://shopify/Product/456']" ], "updated": [], "removed": [] }, "query_variables": { "collectionId": "gid://shopify/Collection/123", "productsId": "gid://shopify/Product/456" } }您的应用现在知道了哪个产品加入了哪个集合：
- action 为 update，因为添加产品会改变集合的成员资格。
- 查询表明 hasProduct 为 true。该查询作为您订阅的一部分运行，因此您在收到交付后无需进行另一次 API 调用或获取集合的完整产品列表。
- fields_changed.added _changed.added 告诉您发生了什么变更。
- query_variables query _variables 为您提供两个 ID。
查询结果反映的是查询运行时的状态，因此请使用 fields_changed 来理解变更，并使用 data 来获取当前上下文。交付结构指南 中有更多示例。
更多可构建的主题
我们从 Product 和 Customer 开始进行开发者预览。我们已将覆盖范围扩展到 Admin GraphQL 中的许多其他关键类型：
- 商品管理： Product 和 Collection
- 客户和公司： Customer 和 Company
- 订单、履行和退货： Order、FulfillmentOrder、Refund 和 Return
- 库存和地点： InventoryItem、InventoryShipment、InventoryTransfer 和 Location
- 内容： Article、Blog 和 Page
- 自定义数据：MetafieldDefinition、Metaobject以及MetaobjectDefinition
每个主题都有其支持的触发器、查询变量和访问范围。请查看Events API 参考文档，以了解您希望订阅的更改内容。
从您的订阅中获取更多价值
将现有的有效载荷复制到 GraphQL 查询并订阅所有变更可能很有吸引力。这能让您获得熟悉的数据，但也继承了大量应用原本就在做的工作。
从应用在某事发生变更时需要执行的操作开始，然后围绕这一点来设计订阅。在集合示例中，我们只需要受影响的成员资格信息。每次交付时加载集合中的所有产品只会增加工作量，而无助于我们处理该变更。
Events 优化指南详细介绍了如何选择特定的触发器、查询受影响的资源，并在保持应用所需数据的同时拆分订阅。它还解释了 Shopify 对查询设置的复杂度限制，以及如何确保在发布配置前您的查询始终处于该限制之内。
当您从经典 Webhook 迁移到 Events 时，请衡量应用接收到的投递次数、每个有效载荷的大小以及其发起的后续 API 调用。这将告诉您变更在哪些方面带来了帮助，以及在哪些方面还有更多工作需要完成。
开始使用
您现有的经典 Webhook 集成将继续正常工作。您可以在同一应用中同时使用两者，并一次迁移一个工作流。对于 Events 尚不支持的主题或订阅模式，请继续使用经典 Webhook。
- 正从 Webhooks 迁移至 Events？：我们建议首先识别一个工作流，在该工作流中您的应用接收大量更新并丢弃其中大部分，或在每次交付时发起其他 API 调用。审视您的处理程序实际执行的操作、它所需的更改以及读取的数据，这将为您确定订阅的起点。请参阅迁移指南以开始操作。
- 完全不熟悉经典 Webhooks 和 Events？：要开始使用，请使用 Shopify CLI 版本 4.83 或更高版本，并遵循入门指南。将您的 events API 版本设置为2026-10，并从参考文档中选择应用所需的话题和触发器。
- 已在使用 Events 开发者预览版？：只需将您的 events API 版本从unstable更新至2026-10，包括任何订阅级别的覆盖设置。查阅版本化的话题参考文档，然后测试并部署更新后的配置。
我们非常乐意了解您利用 Events 构建了哪些功能，以及在何处遇到困难。如果缺少某个话题或触发器阻碍了您的迁移，请在开发者社区中告知我们您试图迁移的工作流。