Webhookとは、あるサービスでイベントが起きたときに、あらかじめ指定したURLへHTTPリクエストで通知を送る仕組みです。
たとえば、GitHubでコードがpushされたらCIを起動する、Stripeで決済が完了したら自社システムの注文状態を更新する、Bitbucketでリポジトリに変更があったら外部サーバーへ知らせる、といった場面で使われます。
Webhookは、こちらから何度も確認しに行く仕組みではありません。相手のサービス側で何かが起きたら、通知がこちらへ届く仕組みです。
この記事では、Webhookの意味、APIとの違い、HTTP POSTで通知が届く流れ、受信側で注意すべきセキュリティと再送対策を、IT用語解説として初心者向けに整理します。
Webhookはイベント通知の仕組み
Webhookは、イベントをきっかけに外部サーバーへデータを届ける仕組みです。ここでいうイベントとは、決済完了、コードのpush、課題の作成、コメント投稿、ファイル更新など、サービス内で起きた出来事のことです。
GitHub Docsでは、Webhookを使うと、ソフトウェアシステムで発生したイベントを購読し、そのイベントが起きたときにサーバーへデータ配信を自動で受け取れると説明されています。つまり、Webhookは「イベントが起きたら通知してもらう」ための入口です。
次の図では、外部サービス、Webhook、自社サーバーの関係を見てください。イベントが配達レーンを通って自社サーバーへ届くイメージで捉えると、APIとの違いが理解しやすくなります。
WebhookとAPIの違い
APIは、こちらから相手のサーバーへリクエストを送り、必要なデータを取りに行く仕組みとして使われることが多いです。一方Webhookは、相手のサービス側でイベントが起きたとき、相手からこちらのURLへ通知が送られます。
この違いは、ニュースを何度も見に行くか、速報通知を受け取るかの違いに近いです。APIポーリングは定期的に見に行く方法、Webhookは変化が起きたときに届く方法です。
次の比較図では、APIポーリングとWebhookの違いを見てください。どちらが優れているかではなく、必要なタイミングと用途が違います。
| 項目 | APIポーリング | Webhook |
|---|---|---|
| 動き方 | こちらから定期的に確認する | 相手からイベント発生時に通知される |
| 向いている場面 | 今の状態を好きなタイミングで取得したい | 変化が起きたらすぐ処理したい |
| 注意点 | 確認回数が多いと無駄が増える | 受信URLを安全に公開する必要がある |
Webhookを構成する4つの要素
Webhookは、単にURLを登録するだけの仕組みではありません。実務では、イベント、送信先URL、HTTP POST、ペイロードをセットで考えます。さらに、送信元が本物か確認するための署名も重要です。
次の図では、Webhookを構成する要素を分けて見てください。最初は「何が起きたか」「どこへ届くか」「どんなデータが届くか」の3点を押さえれば十分です。
ペイロードとは、Webhookで送られてくるデータ本体です。多くの場合、JSON形式でイベントの種類、発生時刻、対象データのID、関連オブジェクトなどが含まれます。
POST /webhook/github HTTP/1.1
Content-Type: application/json
X-GitHub-Event: push
X-Hub-Signature-256: sha256=...
{
"ref": "refs/heads/main",
"repository": {
"name": "sample-app"
}
}Webhookの処理フロー
Webhookを使うには、まず通知を受け取るURLを外部サービス側に登録します。その後、購読したイベントが発生すると、外部サービスがそのURLへHTTPリクエストを送ります。受信側のサーバーは署名などを確認し、必要な処理を行い、成功したことをHTTPステータスで返します。
次の図では、登録から2xx応答までの流れを見てください。Webhookは受け取った後の処理だけでなく、すばやく応答する設計も重要です。
Stripeの公式ドキュメントでも、Webhook endpointは複雑な処理でタイムアウトする前に、成功を示す2xxステータスをすばやく返すことが推奨されています。重い処理はキューへ入れ、あとで非同期に実行する設計にすると扱いやすくなります。
Webhookの代表的な使い道
Webhookは、別のサービスで起きた出来事を自社システムに反映したいときに使います。単なる通知だけでなく、CI/CD、決済、チャット通知、監査ログ、外部ツール連携などにも使われます。
GitHub Docsでは、CIパイプラインの起動、コラボレーションツールへの通知、外部課題管理ツールの更新、本番環境へのデプロイ、監査ログ記録などがWebhookの利用例として挙げられています。
失敗時の再送と重複に注意する
Webhookは便利ですが、ネットワーク越しの通知なので失敗することがあります。受信側がタイムアウトした、5xxを返した、ネットワークが一時的に不安定だった、といった理由で、同じイベントが再送されることがあります。
次の図では、失敗、再送、重複対策の流れを見てください。Webhookは「必ず1回だけ届く」と決めつけず、同じイベントが複数回届いても壊れないように作るのが実務では重要です。
重複に強い処理を、冪等性のある処理と呼ぶことがあります。冪等とは、同じ操作を複数回実行しても結果が変わらない性質です。たとえば、同じ決済完了イベントを2回受け取っても、注文を2重に発送しないようにする必要があります。
安全に受け取るためのポイント
Webhook endpointは、外部サービスからHTTPリクエストを受ける入口です。そのため、ただURLを公開するだけでなく、本物のサービスから届いた通知か、改ざんされていないか、失敗したときに追跡できるかを確認します。
次の図では、Webhookを安全に受け取るためのチェックポイントを見てください。特に、署名検証、HTTPS、すばやい2xx応答、ログ、イベント選択、重複対策は最初から設計に入れるべきです。
Stripeの公式ドキュメントでは、Webhookが本当にStripeから送られたものか確認するために署名検証を行うことが推奨されています。GitHubにもWebhook deliveryの検証に関する公式ガイドがあります。どのサービスでも、署名やsecretの扱いは公式ドキュメントに従うのが安全です。
Webhookでよくある誤解
WebhookはAPIの一種として説明されることもありますが、通常のAPI呼び出しとは向きが違います。自社システムが外部APIへ取りに行くのではなく、外部サービスが自社の受信URLへ送ってきます。
また、Webhookを登録したからといって、自動的に何でも安全になるわけではありません。受信URLが公開されるため、署名検証やsecret管理、再送対策、ログ確認が必要です。
さらに、Webhookはリアルタイムに近い通知には向いていますが、最終的な正しさを確認したい場合は、必要に応じてAPIで最新状態を取り直す設計も検討します。決済や権限変更など重要な処理では、Webhookだけを盲信しないことが大切です。
既存記事とあわせて読む順番
Webhookは、API、HTTP、URL、CORS、非同期処理の理解とつながっています。先にHTTPリクエストやWeb APIの基本を押さえると、Webhookの受信処理が読みやすくなります。
- APIとは？APIとWeb APIの違い
- REST APIとは何か？
- HTTPとは？HTTPSとは？
- 【JavaScript】fetch APIとは？GETとPOSTの使い方
- 【JavaScript】CORSとは？Access-Control-Allow-Originの意味
公式情報と確認先
Webhookはサービスごとにイベント名、ペイロード、署名ヘッダー、再送仕様が違います。実装時は、必ず利用するサービスの公式ドキュメントで確認します。
- GitHub Docs: About webhooks
- GitHub Docs: Webhook events and payloads
- Stripe Docs: Webhooks
- Bitbucket Cloud: Manage webhooks
まとめ
Webhookとは、外部サービスでイベントが起きたときに、あらかじめ指定したURLへHTTPリクエストで通知を送る仕組みです。
Webhookを理解すると、API連携、決済連携、CI/CD、通知システムの仕組みが一段読みやすくなります。まずは「イベントが起きたら指定URLへ届く通知」として押さえましょう。