🔔 Webhookとは何か ― イベント駆動連携の基本を押さえる

🧭 はじめに

Webhookは、「あるシステムで何かが起きたことを、別のシステムに即座に通知する仕組み」 です。 APIが「取りに行く（pull）」仕組みであるのに対し、Webhookは「向こうから届く（push）」仕組みであり、イベント駆動アーキテクチャの基本要素として広く使われています。

本記事では、Webhookの概念・仕組み・用途・設計上の注意点を、BookStackに保存しやすい形で整理します。

📦 Webhookの基本概念

🔁 Webhookの一言定義

Webhookとは、特定のイベント発生時に、事前に登録されたURLへHTTPリクエストを送信する仕組みです。

Webhookは「APIの一種」ではあるが、呼び出す主体が逆である点が最大の特徴。

🔌 APIとの違い（Pull vs Push）

観点	API	Webhook
通信の起点	クライアント	サーバ
データ取得	定期的に取得	イベント時のみ送信
無駄な通信	発生しやすい	最小限
リアルタイム性	低い	高い

「変更が起きたときだけ知りたい」場合、Webhookは非常に効率が良い。

⚙️ Webhookの仕組み

📬 基本フロー

受信側が「Webhook受信用URL」を用意する
送信側にそのURLを登録する
イベント発生
送信側がHTTP POST（またはPUT）で通知
受信側が処理を実行

Webhookの実体はただのHTTPリクエスト。特別なプロトコルは不要。

📄 送信されるデータ

多くの場合、以下の形式で送信されます。

HTTPメソッド：POST
Content-Type：application/json
ボディ：イベント内容（JSON）

例（概念）：

イベント種別
対象ID
タイムスタンプ
追加メタデータ

🧩 Webhookの主な利用シーン

🔔 通知・連携

Gitリポジトリの更新通知
チャットツールへの自動通知
障害・アラート連携

🔄 システム間自動連携

決済完了 → 注文確定処理
フォーム送信 → データ登録
CI完了 → デプロイ実行

Webhookは「人が確認しなくても次が動く」設計を可能にする。

🛡️ セキュリティ上の注意点

🔐 認証・検証は必須

Webhookは外部からURLにアクセスされるため、なりすまし対策が不可欠です。

主な対策：

共有シークレットによる署名検証
IPアドレス制限
ヘッダトークンの検証

検証なしでWebhookを受け取るのは危険。 誰でもリクエストを送れてしまう。

⏱ 再送・冪等性

ネットワーク障害で同じ通知が複数回届く可能性あり
同一イベントを複数回処理しても問題が起きない設計が重要

Webhookは「1回だけ届く」と仮定してはいけない。

🧱 設計上のベストプラクティス

🧠 非同期処理を前提にする

受信後すぐに200 OKを返す
重い処理はキューやバックグラウンドで実行

📊 ログと監視

受信ログの保存
エラー時のアラート

Webhookは「届いたか・処理されたか」が追える設計が理想。

🧩 Webhookと他技術の関係

🔄 ポーリングとの違い

ポーリング：一定間隔で確認
Webhook：必要なときだけ通知

🧵 メッセージキューとの違い

Webhook：シンプル・即時
キュー：高信頼・高可用・再試行制御

Webhookは小さく始めやすいが、大規模ではキューと併用されることが多い。

🏁 まとめ

Webhookは、

イベント駆動
リアルタイム
シンプルなHTTP

という特性を持つ、現代的なシステム連携の基礎技術です。

APIと対立する概念ではなく、 「Pull（API）とPush（Webhook）」を適材適所で使い分けることが重要です。

Webhookを理解すると、自動化・連携・拡張性の設計視野が一段広がる。