Webhookを受信する前に確認すること
Webhookを受けるには、送信側の都合でいつ届いても受け付けられるHTTPSの入口が要る。ただしURLを公開しただけでは、送信元が本物か、受け付けた通知を処理しきれたか、止まっていた間の通知をどう取り戻すかは決まらない。「受け付けた」と「業務の処理が終わった」を分けて設計してから、置き場所を選ぶ。
受信前に埋める要件票
| 項目 | 書き出す内容 |
|---|---|
| 入口 | 公開されたHTTPS URLを誰が用意し、証明書とドメインを誰が更新するか |
| 送信元の確認 | 署名検証に使う秘密の値と、検証に必要な受信データ（加工前の本文など）をどう扱うか |
| 受付の記録 | 検証に通った通知を、処理が失敗しても後でやり直せる場所（キューやデータベース）へどう残すか |
| 応答 | 送信側の待ち時間に収まるよう、どの時点で成功を返すか |
| 重複 | 同じ通知が2回届いた時、何を見て処理済みと判断するか |
| 順序 | 通知が発生順に届かなくても結果が壊れないか |
| 取りこぼし | 入口が止まっていた間の通知を、自動の再送・手動の再送・APIでの再取得のどれで取り戻すか |
| 担当 | 受信の失敗に誰が気づき、復旧作業を誰が行うか |
具体的な仕様は送信するサービスごとに違う。以下は決済サービスのStripeを例にした確認で、他のサービスに同じ条件を当てはめない。
Stripeを例にした確認
入口と送信元の確認。 Stripeは、登録するエンドポイントを公開されたHTTPS URLとしている。送信元の確認にはStripe-Signatureヘッダーの署名検証を使い、検証には加工していないリクエスト本文が必要だと注意している。IP許可リストと署名検証の両方を使うことも勧めている。
応答。 複雑な処理を始める前に成功のステータスコードを素早く返し、受け取ったイベントは非同期のキューで処理するよう案内している。
再送と取りこぼし。 本番環境では配信に失敗したイベントを一定期間自動で再送するが、送信先を無効化・削除すると以降の再送は行われない。自動再送とは別に、ダッシュボードやStripe CLIからの手動再送があり、それぞれ使える期間が決まっている。入口の停止中に配信できなかったイベントは、イベント一覧のAPIで配信に失敗したものを絞り込んで取得でき、APIで取得できる期間にも上限がある（未配信のイベントの処理）。
重複と順序は別の問題。 同じイベントが複数回届くことがあるため、処理済みのイベントIDを記録して重複を避ける。これとは別に、イベントが生成順に届く保証はないため、到着順に依存せず、足りない情報はAPIで対象のオブジェクトを取得して補う。
出典はStripe Docs: Webhooks（自動再送・手動再送・イベントの順序・ベストプラクティスの各節）と上記の未配信イベントの手順。確認日（2026年9月14日）時点では、本番の自動再送は最長3日、手動再送はダッシュボードでイベント作成から15日・CLIで30日まで、イベント一覧APIは過去30日分と記載されている。期間は変わりうるため、設計時に公式ページで確かめる。
受付を記録してから成功を返す
公式の「素早く2xxを返す」「非同期のキューで処理する」を、このサイトでは次の順序で満たす設計を目安にしている。
- 加工前の本文で署名を検証する。失敗したら処理しない
- 検証に通った通知を、キューやデータベースなど再処理できる場所に保存し、保存が成功したことを確認する
- 成功のステータスコードを返す
- 保存した通知を別の処理で読み出し、イベントIDで重複を除いてから業務処理を行う
保存より先に成功を返すと、その直後に処理が落ちた場合、送信側は配信済みと扱い、こちらには記録が残らない。Functions型の実行環境では、応答を返した後の処理が打ち切られることもある（Cloudflare Docs: Workers Limits、確認日: 2026年9月14日）。受付の成功と業務処理の成功は、ログや監視でも分けて見る。
トンネルを入口に使う場合
手元のPCを外部に公開するトンネルは、開発中の動作確認には便利だ。Stripeもローカル環境しかない場合の方法として、トンネリングツールでテスト用の公開URLを一時的に作る手順を示している。ただし、手元のPCで一時的に開いたトンネルだけでは、PCの電源、回線、再起動後の復旧を誰が担うかという要件を満たせない。トンネルを本番の入口に使うなら、製品の仕様、契約、接続先を含む構成ごとに、停止時の扱いを確認する。
置き場所の選び方
要件票の入口と受付の記録を満たせれば、専用の仮想サーバーを常時起動することは必須ではない。
- 受付と保存が短時間で終わり、キューやデータベースをマネージド機能で用意できる → Webhookを受けられるFunctionsやPaaSのWebサービスを確認する
- Webhookを受けるソフトウェア（n8nなど）をそのまま動かしたい → そのソフトのクラウド版や、対応するPaaSで足りるかを確認する
- OSやネットワークを自分で設定する必要があり、保守の担当が決まっている → 自己管理VPSが候補になる
方式の候補は自己管理VPSを契約するか決める前の確認ツールで確かめられる。受信後の処理を動かすアプリの置き場所は小規模アプリはどこで動かすかで整理している。