TERM 045
Webhook
イベントが起きたら、HTTPで相手へ知らせる
Webhookは、特定のシステムでイベントが発生した瞬間に、あらかじめ登録された外部のURLへHTTPリクエストを送信してリアルタイムに通知する仕組みです。受信側が定期的にサーバーへ問い合わせるポーリング（Polling）の無駄な通信を削減できます。
イベント発生時に別のシステムへHTTPで通知する仕組みの全体像。
CONTENTSこの記事の目次＋
01 — DEFINITION
Webhookとは
何か
Webhookは、特定のシステムでイベントが発生した瞬間に、あらかじめ登録された外部のURLへHTTPリクエストを送信してリアルタイムに通知する仕組みです。受信側が定期的にサーバーへ問い合わせるポーリング（Polling）の無駄な通信を削減できます。
02 — HOW IT WORKS
仕組みを
3段階で見る
細部へ入る前に、入力から結果までの役割を順番に捉えます。
出来事が発生
支払完了やPushなど、通知対象の状態変化が起きる。
→登録URLへ送信
イベント固有のIDとペイロードをHTTPリクエストとして指定URLへ送信する。
→検証して受理
リクエストの署名検証とイベントIDの重複確認を行い、即座に200 OKの成功レスポンスを返す。
Webhookを理解するときの、最小の処理単位です。
03 — ESSENTIALS
押さえるべき
3つの要点
名前だけでなく、この3点の関係まで理解すると実装へつなげやすくなります。
受信エンドポイント
安全なHTTPSで公開し、タイムアウトを防ぐため最小限の処理で素早く成功応答を返します。
送信元の検証
事前共有シークレットから生成されたHMAC署名を、生のリクエストボディを使って検証します。
重複の識別
処理済みIDを記録し、同じ通知の再実行を防ぎます。
04 — REAL WORLD EXAMPLE
決済完了を注文へ反映する
決済サービスが非同期で支払結果を確定します。
- 01
payment.succeededイベントのリクエストを受信する
- 02
リクエストヘッダーの署名とイベントIDの重複を検証する
- 03
メッセージキューへ非同期に引き渡し、注文状態を確実に1回だけ更新する
05 — WATCH OUT
理解するときの
注意点
便利な仕組みほど、守備範囲と失敗の前提を明確にします。
受信したボディを先にパース・加工しない
改ざん検知の署名は送信された生のHTTPボディ文字列に対して計算されているため、JSONパースなどの加工を行う前の生データで検証する必要があります。
重い処理を受信時に同期実行しない
Webhook受信時は署名検証とメッセージキューへの投入のみを行い、即座にレスポンスを返すことで送信元のタイムアウトや無用な再送を防ぎます。
IN ONE SENTENCE
Webhookとは？
イベント発生時に別のシステムへHTTPで通知する仕組み。