【Square】ローカル環境でwebhookを受け取る方法｜ngrokやCloudflare Tunnelとは何か？使い方を実例で解説（Next.js/Firebase Emulator）

Square_-prograshi（プロぐらし）-kv Square
記事内に広告が含まれていることがあります。

Square決済の導入時、避けて通れないのがWebhookの連携テストです。

しかし、ローカル環境で開発していると「Squareからの通知が自分のPCに届かない」という壁に多くの開発者が直面します。それもそのはず、外部サーバーであるSquareは、あなたのPC内（localhost）を直接見ることができないからです。

そこで欠かせないのが「ngrok」や「Cloudflare Tunnel」といったトンネリングツールです。

ここでは、そもそもこれらのツールがどのような仕組みで動いているのかという基礎知識から、最も手軽なngrokを使ってローカル環境でWebhookを受信する具体的なステップまでを、実例を交えて詳しく解説しています。


ローカル環境（localhost）に通常のwebhookは届かない

ローカル環境など、公開されているURL（外部からアクセス可能な住所）が存在しない場合、Squareのサーバーは、あなたのPC環境（localhost）を直接見ることができません。

このため、通常のSquareからのwebhookは届きません。

ローカル環境などの特殊な環境でwebhookを受け取るためには、インターネット側からローカル環境へ通信を転送するトンネルを作る必要があります。

Point

SquareのWebhook要件は、https://～ で始まる公開URLを宛先にすること。


ローカル環境でwebhookを受け取る方法

Squareのwebhookを受け取るためには、ローカル環境⇔公開URLをつなぐURLを発行する必要があります。

その方法には主に２つあります。

ローカル環境でwebhookを受け取る方法
  • ngrok（デバッグ向き、毎回URLが変わる）
  • Cloudflare Tunnel（検証環境向き、URL固定、デバッグは弱め）


ngrok（エングロック）

ngrok（エングロック）は、アメリカの ngrok Inc. という企業が提供しているサービスです。

ngrokを使うと、インターネット上に https://xxxx-xxxx.ngrok-free.app という「外向きの住所」を一時的に発行してくれます（トンネル）。

最大の特徴は、とにかく手軽なことで、コマンド一つですぐに公開できます。、

また、webhookの結果として表示される情報が充実しているのでデバックに向いています。

開発者の間で非常に有名で、ドキュメントや解説記事が豊富です。

無料版だと通信回数などの制限があります。特に、起動するたびにURLが変わるという制限は開発時に押さえておく必要があります。


Cloudflare Tunnel（クラウドフレア トンネル）

Cloudflare Tunnel（クラウドフレア トンネル）は、世界最大級のネットワーク・セキュリティ企業のCloudflareが提供しているサービスです。

ngrokに比べ、高機能で安定しています。自分の持っている独自ドメインを簡単に割り当てられます。

無料枠でもURLを固定しやすく、長時間運用に向いています。

設定にはCloudflareのアカウントが必要で、ngrokよりは少しだけ手順が多いです。

「URLを固定して安定して使い続けたい」「セキュリティ設定も細かくしたい」という人に向いています。


ngrok vs Cloudflare tunnel比較表

項目ngrokCloudflare Tunnel
手軽さ爆速少し設定が必要
URLの固定無料版では固定できない無料でも独自ドメイン等で固定可能
主な用途一時的なデバッグ、Webhookテスト常設デモ環境、自宅サーバー公開
信頼性高い非常に高い


よくある割当パターン
  • デバッグ → ngrok
  • 検証環境 → Cloudflare Tunnel
  • 本番 → 公式のhttps://～

※検証環境をfirebase hostingなどで公開している場合は、公開URLが使えるので、トンネルは不要です。


ngrokの使い方

ここでは、ngrokの使い方について解説します。

（前提環境）Firbase emulatorを使い、Squareのサンドボックスでwebhookを行います。cloud functionsに設定したSquare webhook用の関数をendpointとして設定します。


ngrokのインストール（直接DL）

ngrokのダウンロードページに移動し、ngrokをインストールします。ここでは、Windows Store Installerを使います。

Download ngrok for Windows | ngrok
Download ngrok for Windows — step-by-step installation instructions, authtoken configuration, and quick-start examples t...
ngrok.com
補足1

Windows store installer経由でインストールした場合、パスが自動的に通ります。

インストール後に「ngrok –version」を実行し、バージョンが表示されれば正しくインストールできパスも通っています（ngrokコマンドが使える）

> ngrok --version
ngrok version 3.36.1-msix-stable
補足2

今回のプロジェクトで一時的に使用するだけの場合、フォルダをダウンロードしてプロジェクトディレクトリに置くこともできます。

この場合、パスを通さずに直接exeファイルを叩くこともできます。（※パスを通さない場合は他のプロジェクトで参照するときは毎回ファイルパスを指定する必要があります）

パスを通す場合は、システム環境設定でパスを通す必要があります。

「Windowsの検索で『システム環境』と検索 ＞ 『システム環境設定の編集』を開く ＞　『環境変数』を選択　＞ 『新規』」


ngrokアカウントの作成とauthtokenの取得

ngrokは「ngrok アカウント」と「authtoken」が必須です。以下URLからngrokアカウントを作成します。

ngrok Sign Up — Secure Tunnels, Domains & API Gateway
Create a free ngrok account and start building secure tunnels, custom domains, and API gateways in minutes. Sign up with...
dashboard.ngrok.com

Googleアカウントでも作成可能です。

ダッシュボードに入ったら右メニューの「Your Authtoken」を選択し「COPY」します。


以下のコマンドを実行してコピーしたトークンを登録します。

ngrok config add-authtoken あなたのトークン

これで、トークンの登録が完了です。

Authtoken saved to configuration file: C:\Users\～\AppData\Local/ngrok/ngrok.yml


ngrokの起動

以下のコマンドを実行してngrokを起動します。

ngrok http 5001

起動すると、Forwardingという項目に公開URLが表示されます。

Forwarding     https://xxxx-refresh-stunner.ngrok-free.dev -> http://localhost:5001

この「https://xxxxxxx-refresh-stunner.ngrok-free.dev」がパブリックとローカル環境をつなぐトンネルです。


Webhook用のURLの確認（Firebase Emulatorの場合）

Firebase Emulatorの場合は、上記の公開URLをそのまま使うことができません。以下のように「プロジェクトID」や「関数名」を指定する必要があります。

[ngrokのURL]/[プロジェクトID]/[関数のリージョン]/[関数名]

例: https://xxxx-refresh-stunner.ngrok-free.dev/my-project/asia-northeast1/squareWebhook


現在使用しているプロジェクト名は「firebase use」で確認できます。

 firebase use
Active Project: stg-app

ローカルの関数のリージョンはfirebase emulator:startしたときに表示されます。（本番（クラウドの）関数一覧を確認したいときは「firebase functions:list」で確認できます）

+  functions[asia-northeast1-squareWebhook]: http function initialized (http://127.0.0.1:5001/stg-app/asia-northeast1/squareWebhook).


また、例えば、suquareのWebhookで叩いてもらう関数（squareWebhook）は以下のようになっています。

// ── squareWebhook ─────────────────────────────────────────────────────────────

/**
 * Square Webhook を受信して Firestore を更新する。
 * - HMAC-SHA256 署名検証を行い、不正なリクエストを拒否する。
 * - reference_id から uid を逆引きし、users/{uid}.payment を更新する。
 * - paymentsコレクションにイベントを記録（eventId で二重処理防止）。
 * - payment.failed 時は sessions/{uid} を revoked に更新して強制ログアウトを発火する。
 */
export const squareWebhook = onRequest(
  { region: 'asia-northeast1' },
  async (req, res) => {
    if (req.method !== 'POST') {
      res.status(405).send('Method Not Allowed');
      return;
    }
・・・・・

これらをまとめるとSquareに登録するWebhook用のURLは以下になります。

[ngrokのURL]/[プロジェクトID]/us-central1/[関数名]

例: https://xxxx-refresh-stunner.ngrok-free.dev/stg-app/asia-northeast1/squareWebhook


SquareのwebhookにURLを登録する

Square Developer Dashboard を開き、対象のアプリケーションに入ります。Sandbox モードになっていることを確認します。


Webhook subscriptionsを作成します。

MEMO

Webhookの送信先のことを「Endpoint」といいます。Squareでは「Endpointの設定＝subscription（購読）の設定」となります。


サブスクリプションの設定は以下の項目を入力します。

サブスクリプションの設定
  1. Subscription name：任意（local-webhookなど）
  2. Notification URL： Webhook用のURL
  3. API version：デフォルト（最新）
  4. Events: 使うイベントのみを選択
Eventsでallにしない

SquareのWebhookは開発・本番に関わらず、選択したイベントしか通知が来ません。基本的にはpaymentなど使用するイベントのみを選択します。


「Save」すればSubscription（Endpoint）の設定ができます。


Webhookシグネチャ（Signature Key）の登録

送られてきたデータが「本当にSquareから来たものか」を検証するために不可欠な秘密鍵である、SquareのWebhook Signature Key（署名キー）を環境変数として登録します。

Emulatorのcloud functionsを使う場合、functions/.env.localでSquareのサンドボックスのトークンなどと同様にWebhook Signature Keyを保存します。

Square Developerで登録したSubscriptionを選択します。右側のメニューに表示される「Signature key」をコピーして、.env.localに貼り付けます。

SQUARE_WEBHOOK_SIGNATURE_KEY=FB...


functions/.env.localが以下のようになっていれば正解です。

#squareサンドボックス(※functions用)
SQUARE_ACCESS_TOKEN=EAAA...
SQUARE_ENVIRONMENT=sandbox
SQUARE_LOCATION_ID=LP...
SQUARE_WEBHOOK_SIGNATURE_KEY=FB...
注意点

.env.localに記述した内容は全て重要です。必ず.gitignoreに追加してください。


Firebase Emulatorを起動する

.env.localを編集したら、Firebase Emulatorを起動します。※環境変数は起動時に読み込まれます。

firebase emulators:start

データを保存している場合は以下。

firebase emulators:start --import=./saved-data --export-on-exit

「i functions: Loaded environment variables from .env.local.」と表示されていれば、.env.localの環境変数が読み込まれています。


テストイベントを送信する

Square developerダッシュボードで対象のsubscriptionを選択し、「・・・」の「Send test event」を選択します。


送信するイベントを選択し「Send」をクリックします。


Response 200 OKと表示されれば送信完了です。


Emulator側で受け取りを確認できます。

i  functions: Beginning execution of "asia-northeast1-squareWebhook"
>  {"url":"https://xxx-refresh-stunner.ngrok-free.dev/stg-app/asia-northeast1/squareWebhook","severity":"INFO","message":"squareWebhook: ngrok URL を使用"}
>  {"eventType":"subscription.created","severity":"WARNING","message":"squareWebhook: uid が取得できません"}
>  {"eventId":"65bc2e81-bcdc-4add-abfd-7a012b8f3d2a","eventType":"subscription.created","severity":"INFO","message":"squareWebhook: 処理完了"}
i  functions: Finished "asia-northeast1-squareWebhook" in 119.022ms


ngrokでデバックする

ngrokを使うと送られてきたデータの内容を細かく確認することができます。

ngrokを起動したときに表示される「Web Interface」のURLを開きます。

http://127.0.0.1:4040
127.0.0.1


便利機能「再送信（Replay）」

Ngrokのコンソールで「Replay」をクリックすると、同じリクエストをもう一度送信することができます。


以上で、localhostでSquare APIのWebhookの受け取りは完了です。

タイトルとURLをコピーしました