Webhook は、あるサービスでイベントが発生した瞬間に、相手先へ HTTP リクエストを送って知らせる仕組みです。定期的に取りに行くのではなく、送る側が「起きた」ときに通知するのが特徴で、処理の遅れを減らしやすい反面、受け側には安全に受け取るための設計が必要です。自動化、通知連携、外部サービス間のつなぎ込みでよく使われます。
イベント駆動で飛んでくる通知
Webhook の本質は、イベント駆動で動くことです。たとえば「注文が確定した」「フォームが送信された」「ファイルがアップロードされた」といった出来事をきっかけに、送信元が受信先の URL へ HTTP POST を送ります。受信先はそのリクエストを処理することで、必要な後続作業を始められます。
このとき、Webhook は「API を呼ぶ」のと似ていますが、呼ぶ主体が逆になりやすいのがポイントです。通常の API 利用では、利用側が必要なときに問い合わせます。一方 Webhook では、送信元が出来事に応じて先に通知します。つまり、問い合わせ型ではなく通知型の連携です。
HTTP POST とペイロードの形
Webhook は多くの場合 HTTP POST で送られ、本文にはイベント内容が入ります。この本文をペイロードと呼びます。実務では JSON 形式がよく使われ、イベント種別、発生時刻、対象 ID、変更後の値などが含まれます。
例として、注文完了を知らせる Webhook では、次のような情報が載ることがあります。
- event: イベント名
- id: 対象レコードの識別子
- created_at: 発生時刻
- data: 変更内容のまとまり
JSON を使うのは、構造化されたデータをそのままやり取りしやすいからです。受信側では、内容を見て「どの処理を走らせるか」を分岐します。
import json
payload = '{"event": "order.created", "id": 123, "amount": 2500}'
data = json.loads(payload)
if data["event"] == "order.created":
print(f"注文処理を開始: id={data['id']}, amount={data['amount']}")受信側に必要な確認
Webhook は「受け取れれば終わり」ではありません。実運用では、正しい送信元から来たか、同じ通知が重複していないか、内容が壊れていないかを確認します。ここが弱いと、不正なリクエストや二重処理が起きやすくなります。
代表的な確認項目は次のとおりです。
- 署名検証: 送信元が付与した署名を確認する
- トークン確認: 共有トークンや秘密情報で送信元を判定する
- 冪等性: 同じイベントが複数回届いても結果を一回分にそろえる
- タイムアウト対策: 長時間処理をその場でしない
特に冪等性は重要です。Webhook はネットワーク事情で再送されることがあり、受信側が「同じ通知をもう一度来たらどうするか」を決めていないと、在庫更新やメール送信が重複します。イベント ID を保存して、処理済みかどうかを判定する設計がよく使われます。
API ポーリングとの使い分け
Webhook と対になる考え方がポーリングです。ポーリングは、受信側が一定間隔で「新しい更新はあるか」と問い合わせる方式です。Webhook はイベントが起きたら送られてくるので、一般に無駄な問い合わせを減らせます。
| 方式 | 動き方 | 長所 | 短所 |
|---|---|---|---|
| Webhook | 変更時に通知が飛ぶ | 低遅延、問い合わせ回数が少ない | 受信側の公開 URL や安全対策が必要 |
| ポーリング | 定期的に問い合わせる | 実装が単純で制御しやすい | 無駄な通信が増えやすい |
Webhook は、即時性が必要な通知や自動化に向きます。一方、送信元が通知機能を持たない場合や、受信側が外向き通信を制限されている場合はポーリングのほうが扱いやすいこともあります。
運用で効く設計のポイント
Webhook の運用では、処理をなるべく短くし、重い仕事は別のジョブに回すのが基本です。送信元は受信成功の判定として、短い時間で 200 系の応答を期待することが多いため、受信側で長い処理をすると再送や失敗扱いにつながりやすくなります。
また、試験環境と本番環境で URL を分ける、秘密情報を平文で扱わない、ログに個人情報を残しすぎない、といった運用面の配慮も大切です。Webhook は一見シンプルですが、実際には「受ける」「検証する」「重複を防ぐ」「後続処理へ渡す」の 4 段階で考えると整理しやすくなります。
n8n や外部サービス連携での位置づけ
n8n のような自動化ツールでは、Webhook は外部からワークフローを起動する入口としてよく使われます。たとえば、フォーム送信やチャット投稿をきっかけにワークフローを動かし、JSON を整形して別サービスへ送る、といった使い方です。
このとき重要なのは、Webhook が「処理そのもの」ではなく、処理を開始する合図だという点です。受信した内容を基に、API 呼び出し、メール送信、スプレッドシート更新、データベース登録などを順に行うのが一般的です。Webhook を理解すると、サービス間の連携を「画面操作の自動化」ではなく「イベントの受け渡し」として設計できるようになります。
