SquareをShopify Flowに連携する方法
Squareは、POSおよびオンライン製品における決済、注文、返金、お客様情報、在庫の変更について、Webhookを送信します。Workflow Webhooksは、その呼び出しをShopify Flowのトリガーに変換するため、お店側でそれに応じて対応することができます。お客様にタグを付けたり、注文メモを追加したり、社内メールを送信したり、メタフィールドを更新したり――Shopify Flowで可能なあらゆる操作を行うことができます。
このガイドでは、Squareが送信し、Workflow Webhooksが受信・検証を行い、Shopify Flowが処理を行うという一連の流れをすべて設定します。すべてのリクエストにおいてSquareのHMAC署名が確認されるため、Square以外ではワークフローを開始することができません。
どのようなものを作れるか
- Squareを通じて実店舗でご購入いただいた「Shopify」のお客様をタグ付けしてください。
- Squareによる返金が行われた際には、お客様にメモを追加し、サポート担当者が状況を正確に把握できるようにしてください。
- 共有SKUのSquare在庫が閾値を下回った際に、スタッフにメールを送信します。
送信される代表的なイベントは以下の通りです：payment.created、refund.updated、customer.created、inventory.count.updated。
始める前に
- Workflow Webhooks Shopifyストアにインストールされています。
- Shopify Flow インストール済みです。これは、ShopifyのApp Storeから無料で入手できます。
- Webhookを作成する権限を持つSquareのアカウント。
ステップ 1 - Workflow Webhooks で Webhook を作成します
- Workflow Webhooks を開き**、[Webhook] → [Create Webhook]** の順に選択し、Shopify Flow で識別しやすい名前（例：
Square events）を付けてください。 - **「認証」**で、「**HMAC」**を選択してください。
- 「署名プロバイダー」で「Square」を選択してください。アプリがヘッダー、アルゴリズム、署名付きペイロード、リプレイウィンドウを自動的に入力してくれます。これ以外に設定する必要はありません。
- 「シークレット」の欄はひとまず空のままにして、「保存」をクリックしてください。ページに表示されているWebhookのURLをコピーしてください。
その他の認証モードについては、認証 を、Shopify Flow に送信するフィールドの選択については、ペイロードのマッピングとShopify Flow変数 をご参照ください。
ステップ 2 - Square にエンドポイントを追加する
Square Developer Dashboard で、ご自身のアプリケーションの「**Webhook」**セクションを開き、コピーした URL を使用してサブスクリプションを追加し、署名キーをコピーしてください。
Squareの署名用シークレットを確認する方法
Webhookサブスクリプションの署名キー（Square Developer Dashboard → Webhook）です。
Webhookの署名に関するSquareの公式ドキュメント（）には、お客様のアカウントに適用される正確な文言とスクリーンショットが掲載されています。
そのシークレットを、Workflow Webhooks の Webhook の**「Secret」**フィールドに貼り付けて、保存してください。それ以降、Square からのすべての配信データは、Shopify Flow に届く前に検証されるようになります。
これが何をチェックするのか
| 何 | 値 |
|---|---|
| 署名ヘッダー | x-square-hmacsha256-signature |
| 署名の位置 | ヘッダー値全体 |
| 何が署名されたのでしょうか | {url}{body} |
| 署名 | HMAC-SHA256、Base64エンコード |
| タイムスタンプ | この送信者には使用されていません |
| リプレイ防止機能 | なし - この送信者はタイムスタンプに署名を行わないため、すべての有効な署名は引き続き有効です |
| その秘密 | プレーンテキストとして使用されます。送信者が表示しているとおりに、そのまま貼り付けてください。 |
署名付きペイロードにおいて、{body} はバイト単位でリクエスト本文をそのまま表し、{url} はこの Webhook の URL です。
これらのいずれかの条件を満たさないリクエストは、401 で拒否され、沿革とトラブルシューティング に記録され、ワークフローは決して開始されません。
ステップ 3 - 「Shopify Flow」ワークフローを作成する
- Shopify Flow でワークフローを作成し、「Workflow Webhooks」トリガーを選択してください。
- **「イベントの記録」**をタップし、Squareからテストイベントを送信してください（または、Workflow Webhooksで「テストを送信」を使用してください）。これにより、Shopify Flowがデータのパターンを学習します。
- 所有しているすべてのWebhookは同じShopify Flowトリガーを起動するため、このワークフローをSquareのみに限定するには、Webhook IDを最初の条件として追加してください。IDはWebhookページに表示されています。
- アクションを追加してください ― お客様にタグを付けたり、メモを追加したり、社内メールを送信したり、メタフィールドを更新したりできます。
ステップ4 - エンドツーエンドでテストする
Squareで実際のイベントをトリガーしてください。**「Workflow Webhooks」→「History」に、ステータスが「Success」**の呼び出しが表示されます。署名が正しくない場合は、その理由が記載された失敗のエントリが表示されます。また、署名付きWebhookの検証 では、どのステップで失敗したかを正確に確認できる署名テスターについて解説されています。
署名が一致しません▾
順に、シークレット（最も一般的な原因は、余分なスペースや、間違った環境のキーの使用です）、送信者が別のエンドポイントのシークレットを使用していないか、そしてSquareとアプリの間でボディが書き換えられていないか、という点です。署名は生のバイト列を対象としているため、JSONのフォーマットを変更するプロキシによって署名が破損してしまいます。 Webhookページの署名テスターには、署名された正確なテキストが表示されます。
どのリクエストでも401エラーが表示されます▾
Webhookの認証が**「HMAC」**に設定され、プロバイダーとして「Square」が選択されていること、シークレットが入力されていること、そしてSquareがアプリに表示されているURL（末尾のコードを含む）に正確に投稿していることをご確認ください。
「履歴」には何も表示されません▾
リクエストは届きませんでした。SquareでURLを再度確認し、Squareの配信ログで受信した応答内容をご確認ください。「404」というエラーは、Webhookの設定が間違っているか削除されていることを意味します。「429」というエラーは、ご利用のプランの呼び出し制限を超えていることを意味します。詳細は プランと利用方法 をご覧ください。
ワークフローが誤ったイベントに対して実行されてしまいます▾
ストア内のすべてのWebhookは、同じShopify Flowトリガーを起動します。ワークフローの最初のステップとして、Webhook IDに基づく条件を追加するか、Squareから送信するイベントを絞り込んでください。
関連情報
- 署名付きWebhookの検証 - 当社が審査済みのすべてのプロバイダー、および審査対象外のプロバイダーの記載方法について。
- ペイロードのマッピングとShopify Flow変数 - ペイロードから適切なフィールドを抽出し、Shopify Flowに取り込むこと。
- 重複配送防止 - Squareが配送を再試行した場合はどうなりますか。
- 沿革とトラブルシューティング - すべてのリクエストのログ（再生機能付き）。