開発・エージェント

Webhookとは

この記事の結論

Webhookとは、あるサービスで決められた出来事が起きたとき、そのサービスの側から、あらかじめ登録しておいたURLへHTTPリクエストで知らせを送る仕組みのことです。
こちらから何度も「変化はあった？」と問い合わせる方式（ポーリング）と違い、出来事が起きた時点で相手から届くため、無駄な問い合わせが要りません。
受け取る側は、送り主の署名を確かめること、すぐに成功の応答を返すこと、同じ知らせが2回届いても1回分として扱うことの3点が実装の要になります（2026-09-26 時点）。

うぇぶふっく／Webhook

あるサービスで決められた出来事が起きたとき、そのサービスの側から、あらかじめ登録しておいたURLへHTTPリクエストで知らせを送る仕組みのことです。

最終更新: 2026-09-26

Webhookとは（意味と読み方）

Webhookとは、あるサービスで決められた出来事が起きたとき、そのサービスの側から、あらかじめ登録しておいたURLへHTTPリクエストで知らせを送る仕組みのことです。読みは「ウェブフック」です。hook は英語で「留め金」「引っかけるもの」を指し、出来事に自分の処理を引っかけておく、と考えると覚えやすい名前です。

GitHub の公式ドキュメントは、Webhook を「ソフトウェアの中で起きる出来事を購読し、出来事が起きるたびに自分のサーバーへデータを自動で届けてもらう」仕組みと説明し、APIをときどき呼んでデータの有無を確かめるポーリングとの対比で位置づけています（GitHub Docs：Webhook について）。

ふつうのAPIは、こちらが呼んだときに相手が答えます。Webhookは向きが逆で、相手のほうから呼んできます。受け取る側は、いつ届くか分からない知らせを待ち受けるサーバーを用意しておく必要があります。

Webhookの仕組み（登録から受信まで）

受け口を用意する：自分のサーバーに、POST リクエストを受け付けるURL（エンドポイント）を作ります。例：https://example.com/hooks/payment
送り主に登録する：相手のサービスの設定画面やAPIで、このURLと「知らせてほしい出来事の種類」を登録します。多くのサービスでは、このとき署名用の秘密の文字列（シークレット）が発行されます。
出来事が起きると届く：送り主が、出来事の内容を JSON にしてリクエストの本文に入れ、登録したURLへ送ります。
受け取って応答する：受け口は中身を確かめ、成功を示す 2xx のステータスコードを返します。

決済サービスの公式ドキュメントでは、本番環境で応答が得られなかった場合、指数バックオフで間隔を広げながら最長3日間、配信を再試行すると説明されています。また、イベントが発生順に届くことは保証されず、同じイベントが複数回届く可能性があるとも書かれています（決済サービスの公式ドキュメント（Webhook の受信））。

AI開発でのWebhookの具体例

リポジトリへの push で処理を始める：コードが push されたら自分のサーバーに知らせを送らせ、テストやデプロイの流れを起動します。ワークフロー自動化のきっかけとして最もよく使われる形です。
決済の完了を受けて利用権を付ける：画面上で「支払い完了」と表示されたかどうかではなく、決済サービスから届く完了の知らせを受けてから、アプリ側の状態を更新します。
AIへの依頼の入り口にする：問い合わせフォームの送信をWebhookで受け、内容をLLMで分類してから担当の窓口へ回します。

AIコーディングエージェントに受け口を書かせることも増えています。その場合は、下の注意点（署名の検証、重複の扱い）がコードに入っているかを、差分を読んで確かめます。

Webhookについてのよくある誤解

誤解：届いたリクエストは送り主からのものだと信じてよい → 実際：URLを知っていれば誰でも送れます。送り主が付ける署名を、共有したシークレットで検証して初めて「本物」と判断できます。
誤解：1つの出来事につき、知らせはちょうど1回届く → 実際：再試行の仕組みがあるため、同じ知らせが2回以上届くことがあります。順番が前後することもあります。
誤解：開発中のパソコンでもそのまま受け取れる → 実際：送り主はインターネット上から送ってくるため、localhostには直接届きません。公開されたURLを一時的に用意するか、送り主が提供する転送用のコマンドを使って試します。

Webhookを受け取る側の注意点

署名を検証する：GitHub は、シークレットを鍵にした HMAC の SHA-256 の値を X-Hub-Signature-256 ヘッダーに入れて送ります。比較には、ふつうの == ではなく、所要時間が一定になる比較関数（Node.js なら crypto.timingSafeEqual）を使うよう案内されています（GitHub Docs：Webhook の配信を検証する）。
検証には加工前の本文を使う：フレームワークがJSONを読み込んで整形した後の本文では、署名が一致しなくなります。
先に 2xx を返し、重い処理は後に回す：時間のかかる処理を終えてから応答すると、送り主の側でタイムアウトとして扱われ、再送の原因になります。
処理済みのイベントIDを記録する：同じIDが再び届いたら処理を飛ばします。これで重複配信による二重処理を防げます。
シークレットはコードに書かない：環境変数などから読み込み、漏れた疑いがあれば発行し直します。

出典・参考資料

よくある質問

Q1. Webhookとは何ですか？
あるサービスで決められた出来事が起きたとき、そのサービスの側から、あらかじめ登録しておいたURLへHTTPリクエストで知らせを送る仕組みです。受け取った側は、その知らせをきっかけに自分の処理を始められます。

Q2. WebhookとAPIの違いは何ですか？
APIは、こちらが呼び出したときに相手が答える仕組みです。Webhookは向きが逆で、出来事が起きたときに相手のほうから呼んできます。変化を知るために何度も問い合わせる必要がなくなる点が違いです。

Q3. Webhookが本物かどうかはどう確かめますか？
送り主が付けてくる署名を検証します。登録時に受け取ったシークレットを使って、届いた本文から同じ計算をし、ヘッダーの値と一致するかを所要時間が一定の比較関数で確かめます。一致しなければ処理しません。

Q4. 同じWebhookが2回届いたらどうすればよいですか？
再試行の仕組みがあるため、同じ知らせが複数回届くことは珍しくありません。処理したイベントのIDを記録しておき、同じIDが届いたら処理を飛ばして成功の応答だけを返します。

Q5. 手元のパソコンでWebhookを試すにはどうすればよいですか？
localhost にはインターネット上の送り主から直接届かないため、一時的に公開URLを用意する方法か、送り主が提供するコマンドで知らせを手元に転送する方法を使います。本番のシークレットとは別の、テスト用の設定で試します。