【ITニュース解説】My webhook catcher taught me that testing Stripe callbacks locally is a lie you tell yourself

システムエンジニアを目指す初心者が開発を進める中で、外部サービスとの連携は避けて通れない重要な要素だ。その中でも「Webhook」という仕組みは頻繁に登場する。Webhookは、あるイベントが発生したときに、その情報を指定されたURLにHTTPリクエスト（主にPOST）として自動的に送信する仕組みのことだ。例えば、ユーザーが商品を購入したときや、GitHubのリポジトリにコードがプッシュされたときなど、様々な場面で利用される。

このWebhookを開発する際に、多くの開発者が直面する共通の課題がある。それは、外部サービスから送られてくるPOSTリクエストを「受け取るための公開URL」が必要になることだ。通常、開発中のシステムは自分のパソコン（ローカル環境）で動いているため、インターネット上に公開されていない。しかし、Webhookの送信元はインターネット上のサービスであることがほとんどなので、ローカル環境で動いているシステムには直接リクエストを送ることができない。

この問題を解決するために、いくつかの方法が使われている。例えば、「ngrok」のようなツールは、ローカル環境のポートを一時的にインターネットに公開し、公開URLを発行してくれる。しかし、ngrokはパソコンがスリープしたりすると接続が切れてしまうことがあり、安定性に欠ける場合がある。また、クラウドサービスに一時的な関数（AWS LambdaやGoogle Cloud Functionsなど）をデプロイしてWebhookを受け取る方法もあるが、これはテストのためだけに利用するにはコストがかかりすぎることがある。このように、開発者はテストやデバッグのために一時的にWebhookを受け取る手段を求めていた。

このような背景から、ニュース記事の著者は「Webhook Catcher」という独自のツールを開発した。これは、一時的に利用できるWebhookレシーバー（受信機）であり、開発者が直面する課題を解決するために設計された。このツールの主な特徴は次の通りだ。まず、たった一度の呼び出しで、すぐに利用できる公開HTTPS URLが生成される。このURLは使い捨てであり、特定の目的にのみ利用される。次に、Webhookの送信元が認証情報を必要としないため、簡単に連携できる。そして、最大100件のイベントを24時間だけ保存し、その後は自動的に削除される仕組みになっている。これはデータベースを使わず、メモリ上で処理されるため、複雑なセットアップや後片付け（クリーンアップ）の作業が一切不要だ。まさに、一時的なテストやデバッグに特化した、シンプルで効率的なツールと言える。

しかし、このツールを開発し、自身のテストスイートで利用する中で、著者は重要な教訓を得ることになる。著者はStripeのような決済フローをエンドツーエンド（最初から最後まで）でテストしていた。具体的には、テスト用のWebhookを送信し、Catcherでそれを受け取り、ペイロード（送られてきたデータ本体）の形式が期待通りであるかを検証するという流れだ。このテストは当初、完璧に機能しているように見えた。Catcherは送られてきた情報を正確に受け取り、テストは常に成功した。

問題が発覚したのは、Webhookの「送信側」が持つリトライ（再試行）ロジックを考慮した時だった。実際のシステムでは、ネットワークの一時的な障害などでWebhookの送信が失敗した場合、送信元は一定時間後に再度送信を試みる（リトライする）という機能が備わっていることが多い。著者のCatcherは、このような送信側のタイムアウトやリトライ動作を意図的にシミュレートしない設計だった。そのため、Catcherを使ったテストでは、仮に実際の連携環境でネットワークの一時的な瞬断が発生してリトライが必要になったとしても、Catcherは常に一度の送信で「成功」と判断してしまい、テストはパスしてしまう。しかし、これは現実の世界での統合が、最初のネットワークのわずかな問題で崩壊する可能性があることを意味していた。テストは成功しているのに、実際の運用では問題が発生するという、まさに「嘘の安心感」を与えていたのだ。

この経験から、著者はWebhookレシーバーに対する自身の「メンタルモデル」、つまり考え方や認識が誤っていたことに気づいた。当初、著者はWebhookレシーバーを「モック（模擬）」として捉えていた。モックとは、テストのために本物のオブジェクトの振る舞いを模倣する、限定された機能を持つ代替オブジェクトのことだ。しかし、この考え方では、現実の複雑なネットワークやサービスの振る舞いを完全に再現することは難しい。

著者は、Webhookレシーバーの真の役割は「モック」ではなく「ミラー（鏡）」であるべきだと結論づけた。ミラーとは、送られてきたものを一切加工せず、そのまま忠実に映し出すものだ。リトライロジック、耐久性（システムが障害に耐えうるか）、順序保証（イベントが送られた順序で受け取られるか）といった特性は、Webhookの「送信側」と、そのイベントを処理する「受信側（消費者）」の責任であり、Webhookレシーバーという「パイプ（通り道）」の責任ではない、というのがその理由だ。レシーバーの仕事は、愚直で信頼性の高いパイプとして機能し、消費者が「実際に何を受け取ったのか」を、バイト単位で、ヘッダー情報を含めて正確に表示することなのである。

この重要な区別が、著者が開発したWebhook CatcherのAPI設計に大きな影響を与えた。フィルタリング、データの変換、あるいは「役に立つ」と称する正規化（データを統一された形式に整えること）といった機能は一切実装されなかった。代わりに、受信した生のボディデータ、HTTPヘッダー情報、そしてイベントが到着した正確なタイムスタンプをそのまま保存するシンプルな設計になった。これにより、Webhookを利用するエージェント（開発者自身）が、何が重要かを自分で判断し、必要な情報を取得できるようになる。

この哲学は、様々なケースでその価値を発揮した。例えば、StripeのWebhookのペイロード形式を確認したり、GitHubのプッシュイベントの内容を検証したりするのに役立った。さらに興味深いケースでは、ある内部サービスからのJSONデータが、なぜかフォームエンコード形式で到着するという問題が発生した際、このCatcherが真価を発揮した。Catcherは送られてきたHTTPヘッダーをそのまま保存していたため、Content-Typeヘッダーが期待する「application/json」ではなく、実際には「application/x-www-form-urlencoded」となっていた「嘘」を、たった一回の確認で暴き出すことができたのだ。これは、送信側が誤ったヘッダーを付けていたために発生した問題であり、Catcherが「ありのまま」を映し出したからこそ発見できたバグだった。

したがって、あなたが外部サービスからのコールバック（Webhookを含む）を受け取るシステムを構築する場合、この教訓は非常に重要だ。まずは、送信元を一時的に生成したフックURLに向け、実際のシステムでテストしたい処理を実行する。そして、その後Catcherに保存されたログを確認し、「実際に何が届いたのか」を読み返すことだ。あなたが「送信したはずの内容」と、「実際にCatcherに到着した内容」との間にギャップがある場合、そのギャップこそがバグの潜む場所となる。送った内容と受け取った内容を比較することで、予期せぬデータの変換、ヘッダーの不一致、ネットワークの問題など、様々な種類のバグや設定ミスを発見できるのだ。

著者が開発し、一般に公開しているWebhook Catcher（https://x402.freeq.one/tools/webhook_catch.html）は、このような「ミラー」としての役割を果たすツールであり、システムエンジニアを目指す初心者にとっても、実際の開発現場でのデバッグやテストにおいて非常に強力な味方となるだろう。このツールを活用し、送信側と受信側の「真実」を照らし合わせることで、より堅牢で信頼性の高いシステムを構築する手助けとなるはずだ。