Next Gen Events が GA 「何が変わったか」と「必要なデータ」が 1 通で届く

図解 ： Next Gen Events 一般提供開始（Classic Webhooks の後継） Developer / API 2026-10 / 一般提供（GA） Next Gen Events が GA 「何が変わったか」と「必要なデータ」が 1 通で届く Classic Webhooks の後継。受け取る変更（triggers）・ペイロードに載せるデータ（GraphQL query）・配信条件（query_filter）をアプリ側で指定できる。変更内容・対象 ID・クエリ結果がまとめて届くので、受信後の追加 API 呼び出しや差分計算が要らなくなる。 このページの構成 そもそも何が変わるのか（30秒で理解） Event を構成する 3 要素 具体例 ： コレクションへの商品追加を受け取る ペイロードの読み方 対応トピック一覧 Classic Webhooks vs Events の比較 サブスクリプション設計のコツ はじめ方（立場別 3 パターン） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Classic Webhooks では「コレクションが変わった」という 通知だけ が届き、何が変わったかはアプリ側で調べる必要があった。 Next Gen Events は、 何が変わったか ＋ 影響を受けたリソースの ID ＋ 指定した GraphQL クエリの結果 をまとめて届ける。 従来（Classic Webhooks） 通知を受ける → コレクションの商品一覧を取得 → 保存済みリストと突き合わせ → アプリを更新。 1 件の変化を特定するためだけに この手間がかかる。 Next Gen Events サブスクリプションで「気にする変更」と「必要なデータ」を宣言。届いたペイロードだけで処理が完結し、受信後の追加 API 呼び出しが不要になる。 2 Event を構成する 3 要素 サブスクリプションはアプリの shopify.app.toml に直接書く。1 つの event は次の 3 要素で構成される。 triggers どの変更が大事か 例 ： 商品がコレクションに追加／削除された、バリアントの価格が変わった。 query そのとき何のデータが要るか GraphQL Admin API のクエリを書くと、その結果がペイロードに入る。関連データやメタフィールドも含められる。 query_filter どの結果を受け取るか 例 ： ステータスが ACTIVE の商品だけに配信を絞る。 3 要素の連携の詳細は公式の Events overview を参照。 query_filter の具体的な書式例は本記事には記載なし。 3 具体例 ： コレクションへの商品追加を受け取る シナリオ ： アプリが検索インデックスを持っていて、 商品がコレクションに追加／削除されるたびに 更新したい。 collection.products を trigger にし、コレクション ID と商品 ID をそのままクエリ変数に使う。 shopify.app.toml [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" } } 4 ペイロードの読み方 action update 商品の追加はコレクションのメンバーシップを変えるため update になる。 data hasProduct: true クエリはサブスクリプションの一部として実行済み。受信後の API 呼び出しも全商品リストの取得も不要。 fields_changed added / updated / removed 「何が変わったか」を示す。この例では added に 1 件。 query_variables 両方の ID コレクション ID と商品 ID がそのまま手に入る。 クエリ結果は「クエリが実行された時点」の状態 を反映する。変化の把握には fields_changed 、現在のコンテキストには data と使い分ける。他の例は公式の delivery structure guide にある。 5 対応トピック一覧 開発者プレビューは Product と Customer から始まり、GA では Admin GraphQL の主要な型に拡大された。 マーチャンダイジング Product / Collection 顧客・企業 Customer / Company 注文・フルフィルメント・返品 Order / FulfillmentOrder / Refund / Return 在庫・ロケーション InventoryItem / InventoryShipment / InventoryTransfer / Location コンテンツ Article / Blog / Page カスタムデータ MetafieldDefinition / Metaobject / MetaobjectDefinition トピックごとに 対応する trigger・クエリ変数・アクセススコープが異なる 。購読したい変更は Events API reference で個別に確認する。 6 Classic Webhooks vs Events の比較 項目 Classic Webhooks Next Gen Events 受け取る変更の粒度 トピック単位 trigger で指定 例 ： collection.products ペイロードの中身 固定 GraphQL で自由に定義 関連データ・メタフィールドも可 配信の絞り込み 記載なし query_filter で結果に応じて配信可否 何が変わったか アプリ側で取得・比較して特定 fields_changed で提示 設定場所 記載なし shopify.app.toml の [events] 今後 既存連携は 引き続き動作 2026-10 で GA。同一アプリで併用可 Classic Webhooks の廃止時期は本記事に記載なし。 7 サブスクリプション設計のコツ やりがち 既存ペイロードを丸ごと GraphQL に移植＋全変更を購読 見慣れたデータは手に入るが、アプリが従来やっていた処理まで持ち越してしまう。コレクション例で毎回全商品を読み込むのは、変化の処理に役立たず負荷だけ増える。 推奨 「変化が起きたら何をするか」から逆算する コレクション例で必要なのは影響を受けたメンバーシップだけ。そこに合わせて trigger とクエリを形作る。 Events optimization guide が扱う内容 01 trigger を具体的に選ぶ 02 影響リソースだけをクエリ 03 サブスクリプションを分割 04 クエリ複雑度の上限チェック Shopify はクエリに 複雑度の上限 を設けている。設定をリリースする前に上限内に収まっているか確認すること。上限値そのものは本記事に記載なし。 移行時は ① 受信する配信数 ② 各ペイロードのサイズ ③ 受信後の追加 API 呼び出し数 を計測する。効果が出ている箇所と、まだ改善余地がある箇所がわかる。 8 はじめ方（立場別 3 パターン） A Webhooks から移行する まず「大量に受信して大半を捨てている」か「毎回追加 API を呼んでいる」ワークフローを特定。ハンドラが実際に何をし、どの変更とデータを使っているかを見る。それがサブスクリプションの出発点。migration guide を参照。 B どちらも初めて Shopify CLI 4.83 以降 で getting started guide に沿う。events の API バージョンを 2026-10 にし、reference から必要なトピックと trigger を選ぶ。 C 開発者プレビュー利用中 events の API バージョンを unstable → 2026-10 に更新（ サブスクリプション単位の上書き設定も含めて ）。バージョン付きトピック reference を確認し、テストしてからデプロイ。 既存の Classic Webhooks 連携はそのまま動く。 同じアプリで両方を使い、ワークフローを 1 つずつ移せる。Events がまだ対応していないトピックやパターンは Classic Webhooks を使い続ける。 9 技術者が押さえるべき5つのポイント 1. 設定は shopify.app.toml で宣言的に [events] と [[events.subscription]] に handle / topic / actions / triggers / uri / query を書く。アプリ設定としてデプロイする構成。 2. trigger と query は独立 変更を検知するフィールドと、取得するデータは別でよい。 query_filter はクエリ 結果 を見て配信可否を決める。 3. data は「実行時点」の状態 変化の事実は fields_changed 、現在の状態は data 。両者を混同しないハンドラ設計が必要。 4. クエリには複雑度の上限がある 「全部載せ」は上限に当たり得る。リリース前に上限内か確認する。トピックごとに trigger・変数・スコープが異なる点も要確認。 5. 併用・段階移行が前提 Classic Webhooks と Events は同一アプリで併用可。 計測（配信数・ペイロードサイズ・追加 API 呼び出し数）→ 1 ワークフローずつ移行 が公式の推奨。プレビュー利用者はサブスクリプション単位の unstable 上書きの更新漏れに注意。 10 業務に活かせる3つのユースケース USE CASE 1 検索・レコメンド用インデックスの差分同期 課題 コレクション変更通知のたびに全商品を取得して突き合わせており、1 件の追加／削除を見つけるだけで API 呼び出しと差分計算が発生している。 打ち手 Collection トピックで collection.products を trigger にし、 hasProduct だけを返すクエリを設定。 fields_changed と query_variables でインデックスを 1 件単位で更新。 効果 受信後の追加 API 呼び出しと全件比較が不要になり、同期処理が軽くなる。 技術メモ 記事のサンプル構成そのもの。 data は実行時点の状態なので、追加か削除かは fields_changed.added / removed で判定する。 USE CASE 2 受注・出荷・返品・在庫の基幹／倉庫連携をスリム化 課題 ERP・WMS 連携で注文や在庫の通知を受けるたびに、詳細を取りに行く API 呼び出しが発生し、不要な通知の破棄も多い。 打ち手 Order / FulfillmentOrder / Refund / Return / InventoryItem / Location などのトピックで、連携先が使う項目だけをクエリに書き、 query_filter で対象外を配信前に除外。 効果 受信件数・ペイロードサイズ・追加 API 呼び出しを減らし、連携の処理負荷を下げられる。 技術メモ トピックごとに対応 trigger・クエリ変数・アクセススコープが異なるため、Events API reference で事前確認。クエリ複雑度の上限にも注意。 USE CASE 3 既存 Webhooks アプリの「計測ドリブン」段階移行 課題 Classic Webhooks で動いているアプリを一括で作り替えるのはリスクが高く、どこから手を付けるべきかの判断材料もない。 打ち手 配信数・ペイロードサイズ・追加 API 呼び出し数を計測 → 「大量受信して大半を捨てる」「毎回 API を呼ぶ」ワークフローから 1 つずつ Events へ移す。未対応トピックは Webhooks のまま。 効果 既存連携を止めずに移行でき、移行前後の数値をそのまま改善効果の根拠として示せる。 技術メモ 同一アプリで併用可。Shopify CLI 4.83 以降、events の api_version = "2026-10" 。プレビュー利用分はサブスクリプション単位の上書きも更新する。 11 提案で使える1行サマリ 「Next Gen Events は、 欲しい変更だけを、欲しいデータ付きで 届ける Webhooks の後継。 受信後の追加 API 呼び出しと差分計算を減らせて、既存 Webhooks と併用しながら 1 ワークフローずつ移行できる。」 source ： shopify.dev / changelog / next-generation-events-are-now-generally-available 原文公開日 2026-10-01