Classic Webhooks の後継。受け取る変更（triggers）・ペイロードに載せるデータ（GraphQL query）・配信条件（query_filter）をアプリ側で指定できる。変更内容・対象 ID・クエリ結果がまとめて届くので、受信後の追加 API 呼び出しや差分計算が要らなくなる。
通知を受ける → コレクションの商品一覧を取得 → 保存済みリストと突き合わせ → アプリを更新。1 件の変化を特定するためだけにこの手間がかかる。
サブスクリプションで「気にする変更」と「必要なデータ」を宣言。届いたペイロードだけで処理が完結し、受信後の追加 API 呼び出しが不要になる。
サブスクリプションはアプリの shopify.app.toml に直接書く。1 つの event は次の 3 要素で構成される。
例 ： 商品がコレクションに追加／削除された、バリアントの価格が変わった。
GraphQL Admin API のクエリを書くと、その結果がペイロードに入る。関連データやメタフィールドも含められる。
例 ： ステータスが ACTIVE の商品だけに配信を絞る。
query_filter の具体的な書式例は本記事には記載なし。シナリオ ： アプリが検索インデックスを持っていて、商品がコレクションに追加／削除されるたびに更新したい。collection.products を trigger にし、コレクション ID と商品 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) } } """
{
"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"
}
}
商品の追加はコレクションのメンバーシップを変えるため update になる。
クエリはサブスクリプションの一部として実行済み。受信後の API 呼び出しも全商品リストの取得も不要。
「何が変わったか」を示す。この例では added に 1 件。
コレクション ID と商品 ID がそのまま手に入る。
fields_changed、現在のコンテキストには data と使い分ける。他の例は公式の delivery structure guide にある。開発者プレビューは Product と Customer から始まり、GA では Admin GraphQL の主要な型に拡大された。
Product / Collection
Customer / Company
Order / FulfillmentOrder / Refund / Return
InventoryItem / InventoryShipment / InventoryTransfer / Location
Article / Blog / Page
MetafieldDefinition / Metaobject / MetaobjectDefinition
| 項目 | Classic Webhooks | Next Gen Events |
|---|---|---|
| 受け取る変更の粒度 | トピック単位 | trigger で指定 例 ： collection.products |
| ペイロードの中身 | 固定 | GraphQL で自由に定義 関連データ・メタフィールドも可 |
| 配信の絞り込み | 記載なし | query_filter で結果に応じて配信可否 |
| 何が変わったか | アプリ側で取得・比較して特定 | fields_changed で提示 |
| 設定場所 | 記載なし | shopify.app.toml の [events] |
| 今後 | 既存連携は引き続き動作 | 2026-10 で GA。同一アプリで併用可 |
Classic Webhooks の廃止時期は本記事に記載なし。
見慣れたデータは手に入るが、アプリが従来やっていた処理まで持ち越してしまう。コレクション例で毎回全商品を読み込むのは、変化の処理に役立たず負荷だけ増える。
コレクション例で必要なのは影響を受けたメンバーシップだけ。そこに合わせて trigger とクエリを形作る。
まず「大量に受信して大半を捨てている」か「毎回追加 API を呼んでいる」ワークフローを特定。ハンドラが実際に何をし、どの変更とデータを使っているかを見る。それがサブスクリプションの出発点。migration guide を参照。
Shopify CLI 4.83 以降で getting started guide に沿う。events の API バージョンを 2026-10 にし、reference から必要なトピックと trigger を選ぶ。
events の API バージョンを unstable → 2026-10 に更新（サブスクリプション単位の上書き設定も含めて）。バージョン付きトピック reference を確認し、テストしてからデプロイ。
[events] と [[events.subscription]] に handle / topic / actions / triggers / uri / query を書く。アプリ設定としてデプロイする構成。
変更を検知するフィールドと、取得するデータは別でよい。query_filter はクエリ結果を見て配信可否を決める。
変化の事実は fields_changed、現在の状態は data。両者を混同しないハンドラ設計が必要。
「全部載せ」は上限に当たり得る。リリース前に上限内か確認する。トピックごとに trigger・変数・スコープが異なる点も要確認。
Classic Webhooks と Events は同一アプリで併用可。計測（配信数・ペイロードサイズ・追加 API 呼び出し数）→ 1 ワークフローずつ移行が公式の推奨。プレビュー利用者はサブスクリプション単位の unstable 上書きの更新漏れに注意。
Collection トピックで collection.products を trigger にし、hasProduct だけを返すクエリを設定。fields_changed と query_variables でインデックスを 1 件単位で更新。data は実行時点の状態なので、追加か削除かは fields_changed.added / removed で判定する。Order / FulfillmentOrder / Refund / Return / InventoryItem / Location などのトピックで、連携先が使う項目だけをクエリに書き、query_filter で対象外を配信前に除外。api_version = "2026-10"。プレビュー利用分はサブスクリプション単位の上書きも更新する。