Webhookをテストするには、到達可能なURLをプロバイダーに提供し、実際のイベントをトリガーし、ハンドラーがペイロードを受け入れて正しく反応することを確認します。難しいのは、アプリケーションが呼び出し元ではなく受信者であるため、「送信」ボタンを押して応答を読むだけでは済まない点です。このガイドでは、ハンドラーをエンドツーエンドで検証するために必要なツール（検査サービス、ローカルトンネル、プロバイダーのトリガー）と、繰り返しのプロセスについて説明します。
Webhooksが通常のAPIよりもテストが難しい理由
通常のAPI呼び出しでは、リクエストを制御します。メソッドを選択し、ボディを設定し、実行し、応答を読み取ります。Webhooksはそれを逆転させます。プロバイダーは、独自のスケジュールで、定義されたペイロードとともにリクエストを送信します。この役割の逆転により、4つのテスト問題が発生します。
まず、デフォルトでは自分でイベントをトリガーできません。payment_intent.succeededイベントはStripeが成功と判断したときにのみ発生するため、強制的に発生させるにはプロバイダーのツールが必要です。
次に、配信は非同期です。イベントはアップストリームのアクションが完了したときに到着するため、テストでは戻り値でブロックするのではなく、インバウンドリクエストをキャプチャする必要があります。
第三に、ペイロードの形状はプロバイダーによって定義されます。ハンドラーは、GitHub、Stripe、またはSlackが送信するものを正確にパースする必要があります。
第四に、ほとんどのプロバイダーはリクエストに署名します。エンドポイントはボディを信頼する前に署名ヘッダーを検証する必要があり、これをスキップするテストは実際のバグを隠します。詳細については、Webhook署名検証に関するガイドを参照してください。
まだWebhooksが統合に適したパターンであるかどうかを検討している場合は、Webhooks vs PollingおよびWebhook vs WebSocketでトレードオフを比較しています。
Webhookテストツールキット
多くの場合、同じセッションで4種類のツールを使用します。生のペイロードを見るためのキャプチャサービス、ラップトップに到達するためのトンネル、実際のイベントを発生させるためのプロバイダーのトリガー、そしてハンドラーを検証するためのアサーションツールです。
1. 検査およびキャプチャサービス
ハンドラーコードを1行も書く前に、プロバイダーを使い捨てのURLに向け、実際に何が送信されるかを確認してください。これらのサービスは公開エンドポイントを提供し、すべてのリクエストをリアルタイムで表示します。
webhook.siteは、ページが読み込まれた瞬間に一意のランダムURLとメールアドレスを提供します。送信されたすべてのものが即座に表示されます。完全なボディ、ヘッダー、メソッドです。無料URLは7日後に期限切れになり、100リクエストに制限され、最大リクエストサイズは10MBです。有料プランでは、永続的なURL、無制限のリクエスト、最新10,000リクエストの履歴が追加されます。
Beeceptorは、Webhookレシーバーとして使用できる無料のHTTPSエンドポイントを提供し、受信ペイロードをリアルタイムで検査できます。また、モックサーバーエンドポイントも提供するため、同じツールからキャプチャとシミュレーションが可能です。
Pipedream RequestBinは、もう1つの広く使用されているリクエストキャプチャツールです。キャプチャサービスは無料制限を頻繁に変更するため、現在のドキュメントでティアの詳細を確認してください。
これらを使用して、「実際のペイロードはどのようなものか？」という1つの質問に答えてください。後で繰り返し可能なテストを構築するときのために、サンプルをコピーしてください。
2. ローカル開発: トンネルでlocalhostを公開する
プロバイダーはマシン上のlocalhost:3000に到達できません。トンネルは、トラフィックをローカルポートに転送する公開HTTPS URLを作成するため、エディターでハンドラーを実行し、ライブでデバッグできます。
ngrokが一般的な選択肢です。インストールし、一度認証してからポートを転送します。
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # forwards a public HTTPS URL to localhost:3000
無料のngrokアカウントでは、自動的に選択された開発ドメインが提供されます。カスタムドメインには有料プランが必要です。
Cloudflareを好む場合は、cloudflaredが単一のコマンドでクイックトンネルを実行します。
cloudflared tunnel --url http://localhost:3000
トンネルが出力する公開URLをプロバイダーのWebhook設定に貼り付けると、インバウンドイベントがローカルサーバーに届きます。このパターンの詳細なウォークスルーについては、Webhookサービスでlocalhost APIをテストする方法を参照してください。
3. プロバイダーからテストイベントをトリガーする
キャプチャURLは、何かが送信されて初めて役立ちます。ほとんどの主要プロバイダーは、要求に応じてテストイベントを発生させるツールを出荷しているため、実際の支払いを作成したりプッシュしたりする必要はありません。
Stripe CLIが最もクリーンな例です。stripe listenコマンドは、Stripeサンドボックスからのライブイベントをローカルパスに転送し、アプリケーション構成に入れるWebhook署名シークレットを出力します。
# すべてのイベントをローカルハンドラーに転送:
stripe listen --forward-to localhost:3000/webhooks
# 特定のイベントのみにフィルタリング:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
リスナーが実行されている状態で、stripe triggerはテストイベントを発生させます。トリガーは適切にバックアップされたAPIオブジェクトを作成し、副次的な効果があることに注意してください。payment_intent.succeededはpayment_intent.createdも発生させます。
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # サポートされているすべてのイベントを一覧表示
GitHubは、リプレイできる短い配信履歴を保持しています。リポジトリに移動し、設定、次に「コードと自動化」の下にあるWebhookをクリックします。Webhook URLをクリックし、「最近の配信」タブを開き、配信GUIDをクリックし、「再配信」をクリックします。重要な制約が2つあります。過去3日間の配信しか再配信できず、リポジトリへの管理者アクセスが必要です。GitHubは失敗した配信を自動的に再配信しないため、リプレイは手動です。
Slackの受信Webhookはテストが最も簡単です。Webhook URLにJSONをPOSTすることでメッセージを送信します。最小限のペイロードはtextフィールドのみです。
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
SlackのWebhook URLは秘密情報です。Slackは漏洩したURLを取り消すため、クライアントサイドのコードや公開リポジトリから遠ざけてください。
4. ハンドラーの検証
キャプチャとトリガーは配管が機能することを示します。ハンドラーが正しいことを証明するものではありません。最後のツールは、作成されたペイロードを送信し、応答と副次的な効果をチェックします。最も基本的な形では、それは代表的なボディを持つcurlコマンドです。
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
単一のcurlはスモークテストには十分です。しかし、CIで実行される繰り返し可能で検証されたテストが必要な場合は不十分です。そこで、専用のAPIツールがその役割を果たします。
Apidogを使用したWebhookのテスト
Apidogは、APIの設計、デバッグ、テスト、モック、ドキュメント作成のためのオールインワンAPIプラットフォームです。専用の「Webhook受信トレイ」はありませんが、このセクションでは、ペイロードの作成、保存、応答の検証、モックサーバーを使用したプロバイダーの代行という点で、Apidogが実際に得意とすることを正直に説明します。
サンプルペイロードを再利用可能なリクエストとして作成・保存する
webhook.siteでキャプチャしたペイロード（またはプロバイダーのドキュメントからコピーしたもの）を取り、それをApidogリクエストに組み込みます。メソッドをPOSTに設定し、JSONボディを貼り付け、ハンドラーがチェックする署名ヘッダーを含む、プロバイダーが送信するヘッダーを追加します。
そのリクエストをエンドポイントに対して保存します。これで、毎回curlコマンドを再入力する代わりに、既知の正しい（または意図的に不正な）ペイロードをハンドラーにPOSTするための、繰り返し可能でバージョン管理された方法が手に入ります。
ビジュアルアサーションビルダーで応答を検証する
ペイロードを送信することはテストの半分です。もう半分は、ハンドラーが何を返すかをチェックすることです。リクエストまたはシナリオステップで、「Post Processors」を開き、「+ Add」をクリックして「Assertion」を選択します。Apidogは、コードなしで設定できる検証ルールを追加します。
アサーションを応答ボディに向け、JSONのルートには$を使用します。例えば、$.data.statusをターゲットにし、条件をEqualsに設定し、succeededと比較します。リクエストを実行すると、結果がAssertionタブに表示されます。ビジュアルアサーションは値を文字列として比較します。型を厳密にチェックする必要がある場合（実数、ブーリアンなど）は、Postman互換のpm.test構文を使用してカスタムスクリプトに切り替えてください。
これにより、「200を返した」が「200を返し、statusフィールドはsucceededであり、注文IDが一致する」に変わります。成功パス、欠落フィールドのケース、不正な署名の拒否をカバーするために、複数のアサーションを1つのシナリオに組み込みます。
モックサーバーをプロバイダーの代わりとして使用する
時には、別の方向性をテストしたい場合があります。つまり、スタック内のサービスがプロバイダーを呼び出す場合です。ローカルテスト中は、実際のプロバイダーに全くアクセスしたくないかもしれません。Apidogのモックサーバーを使用すると、その代わりをすることができます。
Apidogは3種類のモックを提供します。ローカルモックはデスクトップクライアントで実行され、クライアントが開いている間のみ機能します。クラウドモックはApidogサーバーでホストされ、24時間年中無休で実行され、オン/オフを切り替えられます（デフォルトはオフです）。ランナーモックは自己ホスト型のランナーインフラストラクチャで実行され、チーム全体で共有されます。各HTTPエンドポイントにはモックモジュールがあり、デザインモードのAPIタブまたはデバッグモードのモックタブからモックURLをコピーできます。/で始まるパスのみがモック環境にルーティングされます。テスト中にコードをそのモックURLに向け、実際のAPI呼び出しや副作用なしに、統合は予測可能なプロバイダー応答を得ることができます。
Apidog CLIでCIでWebhookテストを実行する
シナリオがローカルで合格したら、Apidog CLIを使用してプッシュごとに実行します。Node.js v16以降が必要です。
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # インストールを検証
シナリオのCI/CD「Command line」タブからアクセストークンとIDを渡して、保存されたシナリオをオンラインで実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
ここで、-tはテストシナリオ、-eは環境（必須）、-dはテストデータ（CSVまたはJSONファイルのパス、または保存されたデータセットID）、-rはレポーターを設定し、cli、html、json、junitを受け入れます。コマンドラインの完全なウォークスルーについては、Apidog CLIチュートリアルを参照してください。
独自のWebhookテストを視覚的に構築し、検証したいですか？Apidogを無料でお試しください。クレジットカードは不要です。
Webhookテストのステップバイステップワークフロー
ツールを組み合わせて、繰り返しの手順を以下に示します。
- 実際のペイロードを検査する。プロバイダーをwebhook.siteのURLに向け、実際のイベントを1つキャプチャします。ボディの形状、ヘッダー、署名形式に注目してください。
- コードに到達させる。ハンドラーをローカルで起動し、
ngrok http 3000またはcloudflaredでトンネルを開き、公開URLをプロバイダーのWebhook設定に入力します。 - 実際のイベントをトリガーする。
stripe trigger、GitHubのRedeliverボタン、またはSlackのPOSTを使用して、トンネル経由で本物のイベントを送信します。 - 署名処理を検証する。同じペイロードを有効な署名で送信し、次に改ざんされた署名で再度送信します。ハンドラーは最初を受け入れ、次を拒否する必要があります。
- 応答と副次的な効果を検証する。ペイロードをApidogリクエストとして保存し、応答ボディとステータスにアサーションを追加し、データベース行またはダウンストリーム呼び出しが行われたことを確認します。
- 自動化する。シナリオをApidog CLIに移行し、変更があるたびにCIで実行されるようにします。
Webhookシステム自体を設計しているのであって、単に消費しているだけではない場合は、信頼性の高いWebhookを設計する方法と支払いWebhookのベストプラクティスが再試行、冪等性、セキュリティをカバーしています。より広範な視点については、Webhook APIガイドとWebhookとイベント駆動型アーキテクチャが、Webhooksがより大きなシステムにどのように適合するかを説明しています。
よくある質問
Webhookをテストするにはどうすればよいですか？
プロバイダーに到達可能なURLを提供し、実際のイベントまたはテストイベントをトリガーし、ハンドラーがペイロードを受信し、署名を検証し、正しいステータスを返し、期待される副次的な効果を実行することを確認します。まず実際のペイロードをキャプチャし、次に検証付きの繰り返し可能なリクエストを構築して、テストが毎回同じ方法で実行されるようにします。
ローカルでWebhookをテストするにはどうすればよいですか？
ハンドラーをローカルポートで実行し、次にトンネルで公開して、プロバイダーがマシンに到達できるようにします。ngrok http 3000またはcloudflared tunnel --url http://localhost:3000を使用し、公開HTTPS URLをプロバイダーのWebhook設定に貼り付け、イベントをトリガーします。受信リクエストはローカルサーバーに届き、そこでブレークポイントを設定してライブで検査できます。
PostmanでWebhookをテストするにはどうすればよいですか？
Postmanは作成されたペイロードをエンドポイントにPOSTし、応答を検証できますが、それ自体で実際の受信Webhookを受信することはできません。Apidogにも同様に、プロバイダーのペイロードとヘッダーでリクエストを作成し、応答ボディとステータスに検証を追加し、再利用可能なテストとして保存します。本物の受信イベントをキャプチャするには、ツールをキャプチャサービスまたはトンネルと組み合わせて使用します。
Stripe Webhookをテストするにはどうすればよいですか？
Stripe CLIを使用します。stripe listen --forward-to localhost:3000/webhooksを実行して、サンドボックスイベントをハンドラーに転送し、署名シークレットを取得します。次に、stripe trigger payment_intent.succeeded（またはstripe trigger --helpからの任意のイベント）を実行して、実際のテストイベントを発生させます。トリガーはバックアップされたAPIオブジェクトを作成し、連鎖反応を引き起こすことがあるため、payment_intent.succeededはpayment_intent.createdも発生させます。
Slack Webhookをテストするにはどうすればよいですか？
受信Webhook URLにJSONをPOSTします。最小限有効なペイロードは{"text":"Hello, world."}で、Content-type: application/jsonヘッダーとともに送信されます。テストが成功すると、メッセージが設定されたチャネルに投稿されます。Slackは漏洩したWebhook URLを取り消すため、URLは秘密にしてください。
Webhook URLをテストするにはどうすればよいですか？
サンプルPOSTをURLに送信し、成功ステータスを返し、正しく動作することを確認します。最も速いチェックは、代表的なボディを持つ単一のcurlです。実際のテストでは、まず実際のペイロードをキャプチャし、有効な署名と無効な署名の両方で送信し、単に200をチェックするだけでなく、応答と副次的な効果を検証します。