ShopifyにおけるWebhookの全てを15分で把握する

この記事の所要時間：15分

ShopifyにおいてWebhookは重要な役割を果たしています。

Shopify Admin APIでは、GDPRに対応した仕様を満たすために、公開アプリに対してWebhookの実装を義務付けています。

また、自社管理のデータベースとShopifyストアのデータを同期したいというニーズを満たすためにしばしばWebhookが使われます。

Shopifyの公式ドキュメントにはWebhookに関する記述があらゆるページに散らばっています。

ShopifyにおけるWebhook活用はポイントや使い所が多くあるのですが、そのおかげで、最初から全てを把握するのが難しい状況になっています。

この記事では、ShopifyにおけるWebhookの全てをまとめます。

しかし、内容は必要最低限に削ぎ落としているので短時間で読めるはずです。

Webhookについて

まずはWebhookについておさらいします。

Webhookはあるシステムから別のシステムに通知をするために使われます。

WebhookはHTTPのPOSTリクエストによってイベントの発生を通知します。

あるシステムで特定のイベントが起きたら、別のシステムのエンドポイントにPOSTリクエストを発行します。

POSTリクエストを受け取ったシステムは、ステータスコードの200番でレスポンスを返します。

ShopifyにおけるWebhookの位置付け

ShopifyにおけるWebhookは、ShopifyのAdmin APIで定義されたイベントに対して設定することができます。

Admin APIで定義されている主要なイベント

イベント発生元	イベント
カート	カートの作成、カートの更新
チェックアウト	チェックアウトの作成、チェックアウトの更新
コレクション	コレクションの作成、コレクションの削除
顧客	顧客の作成、顧客の削除 顧客の無効化、顧客の有効化
顧客グループ	顧客グループの作成、顧客グループの削除 顧客グループの更新
注文	注文のキャンセル、注文の作成 注文の削除、注文の更新 注文のフルフィルメント 注文のお支払い
商品	商品の作成、商品の削除
ショップ	ショップの更新
テーマ	テーマの作成、テーマの削除、テーマの更新
下書き注文	下書き注文の作成、下書き注文の削除 下書き注文の更新
フルフィフメント	フルフィルメントの作成、フルフィルメントの更新
返金	返金申請の発行

これらのイベントに対してWebhookを設定することで、アプリに通知させることができます。

Webhook通知のプロパティは以下になります。

プロパティ	説明
id	Webhook通知のユニークなID。APIでWebhook通知リソースを指定するのに使われる。
topic	イベントの種類。例) carts/create, customers/update
address	イベントが起きた時にPOSTリクエストが送信されるエンドポイント
api_version	Admin APIのバージョン。Webhook通知の作成時に設定される。
created_at	Webhook通知の作成日時
updated_at	Webhook通知が最後に更新された日時
format	POSTリクエストに含まれるデータの形式。JSONかXML。
fields	通知に含めるプロパティの配列。例)”fields”: [“id”,”updated_at”]
metafield_namespaces	Webhook通知に含めるメタフィールドの名前空間。
private_metafield_namespaces	Webhook通知に含めるプライベートメタフィールドの名前空間。

Webhookの受信側がおさえるべき6つのポイント

Webhook通知を受け取る際に抑えるべきポイントが6つあります。

SSL化

ShopifyのWebhookに設定できるエンドポイントはSSL化されている必要があります。サーバ側で有効なSSL証明書を準備しておきましょう。

通知を受け取ったらステータスコード200番で返す

通知を受け取ったらステータスコード200番のレスポンスを返すようにしましょう。

ShopifyのWebhookは300番台のリダイレクトには対応していません。

300番台でレスポンスするとShopify側はエラーレスポンスと解釈します。

また、201番や202番のレスポンスに対する挙動も明確に定義されていないので、使わないようにしましょう。

タイムアウト

WebhookのPOSTリクエストは5秒でタイムアウトします。

そのため、5秒以内に200番のレスポンスを返せるようにする必要があります。

タイムアウトするとエラーレスポンスとみなされ、POSTリクエストが再送信されます。

レスポンスが全くない場合は、48時間にわたって、合計19回のリクエストが送信されます。

19回目のリクエストがエラーレスポンスとなると、通知は自動で削除され、警告メールが開発者に送信されます。

POSTリクエストの独自ヘッダーとWebhook通知の認証

通知のPOSTリクエストには独自ヘッダーが含まれます。以下は独自ヘッダーの一部です。

キー	値の例
X-Shopify-Topic	orders/create
X-Shopify-Hmac-Sha256	ISfefCGpLGgAgrglvrraov9POIff=
X-Shopify-Shop-Domain	ichyaku.myshopify.com
X-Shopify-API-Version	2021-04
X-Shopify-Webhook-Id	b4888e-soee-f4t0-2398-34gd-f39jv394

X-Shopify-Hmac-Sha256はbase64でエンコードされたMAC値です。

MAC値はPOSTリクエストのボディを平文として、共有鍵を用いて計算されます。共有鍵はWebhook通知の作成時に取得します。

POSTリクエストを受け取る側は、その共有鍵を使ってリクエストボディのMAC値を計算し、X-Shopify-Hmac-Sha256の値と一致するか確かめなければなりません。

認証処理を省くとリクエストが途中で改竄されても気づかない可能性があるので必ず実装しましょう。

Webhook通知を取り直す

Webhookを利用して、Shopifyストアと在庫管理DBを連携させているような場合では、通知を受けるシステムが停止すると何が起こるでしょうか？

すでに売り切れている商品に何件も注文が入るかもしれません。

Shopifyの公式ドキュメントでは、受信されなかったWebhook通知を取り直して、後からシステムに流し込む方法を提案しています。

Webhookを登録し直して、システム停止期間のデータを取得し、Webhook受信側の処理に入力するという手順です。

詳しくはMANAGE WEBHOOKS WITH THE ADMIN APIを参照してください。

Webhookの通知は保障されていない

公式チュートリアルでは、以下のように記述されています。

Your app should not rely solely on receiving data from Shopify webhooks. Since webhook delivery is not always guaranteed, you should implement reconciliation jobs to periodically fetch data from Shopify.

https://shopify.dev/tutorials/manage-webhooks

「Webhookの通知は正しく伝達されることが保障されていないので、Webhookからの通知だけに頼るべきではない。定期的にShopifyからデータを取得して整合性をとる処理を実装するべきだ。」と書かれています。

Webhookのリアルタイム性を生かしながら、正確性を補完するような実装や運用が求められます。

ShopifyでWebhook通知を設定する2つの方法

ShopifyでWebhook通知を設定する方法は2つあります。

ストアの管理画面から設定する方法と、APIを使って登録する方法です。

注意点として、管理画面から登録したWebhook通知はAPIからはアクセスできません。

反対に、APIで登録したWebhook通知は管理画面では表示されません。

ストアの管理画面からWebhookを設定する

まずは「設定」から「通知」を選択します。

一番下までスクロールして「Webhookの作成」から作成できます。

Webhookを作成するにはインターネットからアクセスできるエンドポイントを設定しなければいけませんが、Beeceptorのようなツールを使えば一時的にサーバを立ててエンドポイントを作ることができます。

作成したURLをコピーします。

通知するイベントとフォーマットを選びます。URLに上でコピーしたURLを貼り付けます。

「保存」を選択すると、Webhookが作成されます。

APIを通してWebhookを作成する

APIを通してWebhookを作成する方法では、REST APIとGraphQLのどちらも利用できます。REST APIでは2021年5月現在、Webhookに関して6つのエンドポイントが用意されています。

エンドポイント (/admin/api/2021-04/まで共通)	説明
GET /webhooks.json	設定されたWebhook通知のリストを取得
GET /webhooks/count.json	設定された全てのWebhook通知の合計数を取得
GET /webhooks/{webhook_id}.json	webhook_idで指定したWebhook通知の情報を取得
POST /webhooks.json	新しいWebhook通知を作成
PUT /webhooks/{webhook_id}.json	webhook_idで指定したWebhook通知の設定値を更新
DELETE /webhooks/{webhook_id}.json	webhook_idで指定したWebhook通知を削除

以下の記事も合わせて参考にしてください。

【Shopify API】GraphQLとREST の徹底比較

GraphQLではAdminのEvent APIsに、Webhook通知に関する3つのMutationが用意されています。

Mutation	説明
webhookSubscriptionCreate	新しいWebhook通知を作成
webhookSubscriptionDelete	Webhook通知を削除
webhookSubscriptionUpdate	Webhook通知を更新

Webhookの通知状況を確認する

アプリが受信したWebhook通知の状況をダッシュボードで確認することができます。例外として、プライベートアプリでは利用できません。

確認するには、パートナーのダッシュボードから「アプリ管理」を選択します。

確認したいアプリの「Webhook配信」のカラムを選択すると、Webhookに関するメトリクスが表示されます。

Webhook通知が正しく処理されていない場合は、このダッシュボードから原因をある程度特定することができます。

「失敗した配信率」は0.5%を超えると正常ではないと考えられます。アプリをインストールしたマーチャントにも影響が出ますので、対応する必要が出てきます。

Webhook通知のPOSTリクエストは5秒でタイムアウトしますので、応答時間が5秒に近い場合も対応が必要になるでしょう。

Webhookのバージョン更新を行う3つのシナリオ

Webhookの仕様はバージョニングされており、3ヶ月に1回最新版がリリースされます。

アプリ開発者やストア管理者は新しいバージョンを適用することでセキュリティリスクを減らしたり、より強力な機能を使えるようになります。

アプリ開発者は受信するWebhook通知のバージョンを更新できます。

ストア管理者は発行するWebhook通知のバージョンを設定できます。

ここではシナリオ別にバージョンを更新する方法を3つ説明します。

公開アプリで受け取るWebhookのバージョンを更新する

注意: この操作の前にアプリのソースコードを、新しいバージョンの通知を処理できる状態に変更しておく必要があります。

パートナーのダッシュボードから「アプリ管理」を選択します。

更新対象となる公開アプリを選択し、「アプリ設定」を選択します。

イベントサブスクリプションというセクション内の「イベントバージョン」からバージョンを更新することができます。

プライベートアプリで受け取るWebhookのバージョンを更新する

注意: この操作の前にアプリのソースコードを新しいバージョンの通知を処理できる状態に変更しておく必要があります。

ストア管理画面から「アプリ管理」を選択します。

次に、「プライベートアプリを管理する」を選択します。

更新対象のアプリを選択します。

Webhook APIのバージョンという項目で、バージョンを選択して、右下の「保存する」ボタンを選択します。

ストアから配信するWebhookのバージョンを更新する

ストア管理画面で「設定 > 通知」と選択します。

Webhookというセクションで、イベントを選択するとイベント単位でバージョンを更新できます。

公開アプリに必須のWebhookとGDPR対応

公開アプリは3つのWebhookを実装して、GDPRに対応する必要があります。

GDPR(The General Data Protection Regulation)はEUで施行された個人データの収集・保存・管理に関する規制です。

Shopifyでは全ての個人データの取り扱いをGDPRに準拠させています。

そのため、全てのアプリ開発者はアプリをGDPRに準拠させる必要があります。

特に、公開アプリの開発では、GDPRに対応するために3つのWebhook実装が必須となっています。

イベント	要求	イベント発生のタイミング
customers/redact	顧客データの削除	ストア管理者がアプリに対して顧客データの削除を求めた時に、顧客が直前の6ヶ月に注文をしていなかった場合は要求の10日後にイベントが発生する。一方、顧客が直前の6ヶ月間に注文をしていれば、要求から6ヶ月後にイベントが発生する。
shop/redact	ショップデータの削除	ストア管理者がアプリをアンインストールした48時間後
customers/data_request	保存された顧客データの開示	顧客がストア管理者に対してデータの開示を要求した時。

customers/data_requestは、3者間のやりとりなので、ややこしいです。

手順を追って流れを説明します。

1. 顧客がストア管理者に対してデータ開示を要求する。
2. Shopifyはcustomers/data_requestを発生させ、ストアにインストールされたアプリにWebhook通知を送信する。
3. アプリはリソースIDが含まれたWebhook通知を受け取るが、そのタイミングではデータを返さず、単に200番のレスポンスを返す。
4. アプリがIDで指定されたリソースを保存していたら、後にストア管理者に直接データを提供する。
5. 最後に、ストア管理者がデータをまとめて顧客に開示する。

大量のWebhook通知に耐えるインフラ: Amazon EventBridge

Webhookの問題点は、大量のWebhook通知が発行される可能性があることです。

一般的な事例として、マーチャントがセールを開始した直後に、ストアに注文が殺到することがあります。

そのような場合、ストアにインストールされたアプリには大量のWebhook通知が届く可能性があります。

事前に強力なサーバを用意しておくこともできますが、コストは高くつくでしょう。

突然の大量の通知に、柔軟に対応するのは、簡単なことではありません。

この問題に対してShopifyが提案する解決策がAmazon EventBridgeです。

Amazon EventBridgeはイベントを受け取って、Lambda functionなどに橋渡しするサービスです。

イベントドリブンなアーキテクチャであり、スケール性に優れていることが特徴です。

Shopifyブログでは「EventBridgeはアプリとShopifyストアの間に設けられた巨大なバッファーのようだ」と述べられています。

Shopifyでは、Webhookの受け皿としてEventBridgeを使用することができます。

大規模なマーチャントにアプリがインストールされることを想定するなら、EventBridgeは一度は検討すべきサービスでしょう。

まとめ

ShopifyにおいてWebhookは中心的な役割を果たしています。

あらゆるアプリがWebhookを活用して強力な機能を実装しています。

アプリ開発を行う上では知っておかなければいけない技術と言えるでしょう。

ShopifyにおけるWebhookはイベントとの関係で理解する必要があります。WebhookはAdmin APIで規定されたイベントが起きた時に通知されます。

Shopifyから発行されるWebhook通知を処理するにはおさえるべき6つのポイントがありました。

SSL化や、200番でレスポンスを返すことや、通知を取り直す方法など、全て重要なのでおさえておきましょう。

ShopifyでWebhook通知を設定するには、管理画面で設定する方法と、APIを通して設定する方法がありました。

Webhookのバージョンを更新する方法をシナリオ別に3つお伝えしました。公開アプリにおける方法と、プライベートアプリにおける方法と、ストアにおける方法です。

公開アプリで実装が必須となっている、GDPR準拠のためのWebhookについてもお伝えしました。

顧客データの削除と、ショップデータの削除と、保存された顧客データの開示の3つのイベントがあります。

これらに対してWebhookを実装しておく必要があります。

最後に、Webhookの問題点を指摘した上で、Shopifyが提案する解決策であるAmazon EventBridgeを紹介しました。

是非、Webhookを活用して強力な機能を開発してください！