配管なしで Webhook をデバッグする
最終更新:
すべての Webhook 統合は、同じ地味な問題から始まります。プロバイダーのサーバーがあなたのコードを呼ぶ必要があるのに、あなたのコードはノートパソコン上で動いており、ノートパソコンには何も到達できません。だから、署名の検証、ペイロードの形、ハンドラーのロジックという本来の仕事をデバッグする前に、まず配管を作ることになります。トンネル、ステージングへのデプロイ、あなたのマシンへ転送する公開 URL です。本記事は、このサイトの Webhook テスター のような一時レシーバーでそのステップを飛ばす方法についてです。アドレスを作成し、プロバイダーをそこへ向け、イベントをトリガーし、到着したものを正確に読む。そしてドキュメントではなく真実に即してハンドラーを書くのです。
デバッグのループと、それが壊れる場所
健全な Webhook のループは短いものです。プロバイダーでイベントが発生し、プロバイダーは署名付きペイロードをあなたのエンドポイントへ POST し、あなたのエンドポイントは署名を検証し、ボディを解析し、仕事をして 200 を返します。不健全なループ——誰もが覚えのあるもの——は、すべてのステップに霧を加えます。プロバイダーのダッシュボードは、配信が 500 で失敗した、404 で失敗した、あるいは何も言いません。それはあなたのコードが応答したのか、間のプロキシなのか、タイプミスのあるエンドポイント URL なのか。リトライは同じイベント ID で到着します——それとも同じ支払いに対する新しいイベントなのか。ドキュメントは整った JSON の例を示しますが、本番ペイロードには余分なフィールド、例が平らにしたネストしたオブジェクト、そして時には例が一度も触れなかったコンテンツタイプが含まれます。Stripe と GitHub の Webhook ドキュメント（下にリンク）はどちらも同じ規律を強調しています——署名を検証すること、速く応答すること、重複を処理すること——そして実際の配信を見られるようになるまで、そのどれも実践できません。
壊れる場所は、面白いロジックの中にあることはほとんどありません。それは、送信されたと信じているものと、実際に送信されたものの隙間にあります。フレームワークがすでに解析して再シリアライズしたボディに対して計算された署名ヘッダー、間違ったダッシュボードからコピーしたシークレット、switch 文のスペルがわずかに異なるイベントタイプ、ダッシュボードのテストイベントでは動くのに本番の実イベントでは動かないハンドラー。これらはすべて自分のログの内側からは見えません。ログは、コードが最初の誤った仮定を置いた後から始まるからです。自分のコードではない何かによって記録されたキャプチャ済み配信こそ、ループを短くする揺るぎない真実です。
一時レシーバーが買ってくれるもの
一時レシーバーとは、すべてを受け入れてあなたに見せることだけを仕事とする公開 URL です。このサイトの Webhook テスター はワンクリックで 1 つ作成し、30 分間保持し、メソッド、パスとクエリ、ヘッダー、ボディ（各最大 256 KB）とともに最大 50 件の配信を記録し、その後すべてを自動で削除します。それが買ってくれるのは順序です。トラフィックを観察するためだけに書きかけのハンドラーを公開マシンへデプロイし——その後デプロイとハンドラーを同時にデバッグする——代わりに、観察と実装を分離します。まず、複数の実際のイベントが到着するのを見て、その本当の形を学びます。次に、キャプチャしたペイロードに対してローカルでハンドラーを書き、それらを手動で自分のテストへ再生できます。最後に、プロバイダーを本物のエンドポイントへ向け、イベントをもう一度トリガーします。その時点では、正しい配信が正確にどのようなものか、そしてハンドラーがそれに対して何をすべきかをすでに知っています。
会話がチームの境界を越えるとき、それは証拠も買ってくれます。「あなたの Webhook は金額を文字列で送っている」は議論ですが、"amount": "2000" を示すキャプチャ済み配信は事実です。同じキャプチャは、プロバイダーのサポートチケットが尋ねる質問——どのイベント ID、どのタイムスタンプ、どの署名ヘッダーがあったか——に、ログの発掘作業なしで答え、届いていない配信がそもそも送信されなかったのか、誰かが更新を忘れた古いテストアドレスへ送られたのかを確定させます。隣のツールも同じ哲学です。質問がペイロードではなくリダイレクトの場合、HTTP ステータスチェーントレーサー はサーバーの視点から URL が何をするかを示します。
ワークフロー：このツールを使って
1：Webhook テスター を開いてフックを作成します。受信 URL をコピーし、この瞬間からその URL を資格情報として扱ってください。理由は次のセクションで述べます。2：それをプロバイダーの Webhook 設定にテスト用エンドポイントとして貼り付けます——Stripe、GitHub、そしてほとんどのプロバイダーは複数のエンドポイントを許可するため、本番エンドポイントには触れません——あるいは、あなたがコントロールする送信者をデバッグしている場合は、自分のサービスの設定に貼り付けます。3：正直な方法でイベントをトリガーします。ダッシュボードの「テストイベントを送信」ボタンだけでなく、プロバイダーの実際のフロー（テストモードの支払い、使い捨てブランチへの実際のプッシュ）を使ってください。テストイベントは、まさにあなたが気にするフィールドで実イベントと異なることがあるからです。4：キャプチャを読みます。まずメソッドとコンテンツタイプを確認し、次に署名とイベントヘッダーを確認し、次に、整形された見た目を信頼する前にボディを生テキストとして確認します。
5：そのキャプチャに対してハンドラーを書くか修正します。受信したそのままの生ボディに対して署名を検証します——キャプチャが未解析のバイトを示すのはそのためです——そして、リトライを通じて安定していることが今や確認できるイベント ID に対してハンドラーを冪等にします。6：フックを削除し（または 30 分の有効期限を待ち）、プロバイダーからテスト用エンドポイントを取り除き、配信を本物のハンドラーへ向け直します。7：イベントをもう一度トリガーし、自分のエンドポイントが応答するのを見ます。今度失敗するなら、キャプチャした良い配信とハンドラーの振る舞いの違いこそがバグのすべてであり、それは推測ではなく検査できる違いです。
安全：URL が資格情報です
誰でも読めるレシーバーにはログインは不要で、その便利さには注意すべき代償があります。URL の中のフック ID が唯一の資格情報であり、送信と閲覧の両方を認可します。スクリーンショット、チャットログ、画面共有などから URL を入手した人は誰でも、フックが有効な間、キャプチャされるすべてのペイロードを読むことができます。だから規則はパスワードの規則です。URL を決して公開投稿せず、稼働中の本番フィードには決して使わず、セッションが終わったら、キャプチャに 30 分を過ごさせるのではなくフックを削除してください。ペイロードも反対側から同じ敬意に値します。実際の支払いやプッシュのペイロードには、顧客のメールアドレス、注文の詳細、公開 gist には貼らないようなメタデータが含まれることがあり、キャプチャされた配信はまさにその種の文書です。テストモード、使い捨てのリポジトリ、合成イベントが存在するのは、デバッグの成果物に盗む価値のあるものが何も含まれないようにするためです。
テスター自体の制限は安全の話の一部であり、ツールページに明記されています。キャプチャは、フックが期限切れになるか削除されるまでの間だけチェッカーサーバーに保存され——最大でも 30 分——ボディは 256 KB、フックは 50 リクエストに制限され、レシーバーは何かを取得したり、追跡したり、再生したりすることは決してありません。そのため、キャプチャされたペイロードがサーバーからの送信トラフィックに変わることはありません。それでも判断はあなたに残ります。ペイロードが他人の手に渡れば問題になるようなものなら、それは共有ビューアーにはそもそも属しません。そのデバッグセッションには、本番シークレットに対してそうするように、自分のインフラを使ってください。便利なツールが居場所を獲得するのは、デバッグの日々の大半を占める低感度の仕事においてです。
制限：受信と検査のみ
このツールが意図的にしないのは、検査の後のすべてです。配信をあなたのノートパソコンへ転送しません（それはトンネルの仕事であり、ハンドラーが存在してリアルタイムに反復しているとき、トンネルこそが正しいツールです）。キャプチャしたリクエストを本物のエンドポイントへ再生しません。何も変換も署名もしません。そして 30 分を超える履歴は保持しません。こうした不在こそが設計です。転送するレシーバーはあなたのトラフィックが流れるプロキシであり、再生するレシーバーは送信者であり、どちらも 30 分の受信トレイよりも大きな信頼です。テスターは、それが合う段階——ハンドラーを構築する前と構築中に真実を見ること——に使い、統合が稼働した瞬間からは、あなた自身の認証とログの背後にあるあなた自身のエンドポイントに引き継がせてください。