Webhook

どのようなものか

Webhookは、あるサービスで何かが起きたときに、そのサービスが別のサー
ビスへ送るHTTPリクエストです。支払いが通った、請求書の代金が支払われ
た、時間のかかる処理が終わった、といった出来事を伝えます。受信側はあ
らかじめURLを登録し、送信側は各イベントの内容をそのURLに送信します。
Standard
Webhooks仕様は、Webhookを「HTTPコールバックの一般的な呼び名」とし、
サービス同士がイベントを通知するための経路と説明しています。英語では
web
hookと2語で書かれることもありますが、Stripe、GitHub、この仕様はいず
れも1語で書きます。

仕様はまた、WebhookをサービスのAPIの一部、いわば逆向きに動くAPIと説
明しています。通常は、何かを必要とするクライアントがサービスを呼び出
します。Webhookでは、知らせがあるサービスがクライアントを呼び出しま
す。典型的なAPI連携では、片方がAPI呼び出しを、もう片方がWebhookを受
け付けるため、双方がHTTPサーバーを動かします。ただし、独自のリクエス
トAPIを提供せずにWebhookだけを送るサービスもあります。送信側をプロ
デューサー、受信側をコンシューマーと呼び、受信側が登録するURLを
Webhookエンドポイントと呼びます。

仕様はJSON本文を持つHTTP
POSTを推奨していますが、特定のペイロード形式や構造を必須にはしていま
せん。推奨する本文には、ピリオドで階層を区切る`type`（`invoice.paid`
など）、イベント発生時刻をISO
8601で表す`timestamp`、`data`配下または最上位に置くイベントデータが
含まれます。追加のメタデータも、どちらに置いても構いません。配信のメ
タデータはヘッダーに置きます。`webhook-id`がイベントを識別し、
`webhook-timestamp`が今回の配信試行の時刻をUnix秒で記録し、
`webhook-signature`が真正性を確認するための署名になります。Stripeや
GitHubは、`Stripe-Signature`や`X-Hub-Signature-256`など、それぞれ独
自のヘッダー名を使い、検証規則も異なります。Stripeは試行時刻と本文を
まとめて署名しますが、GitHubのHMACが対象とするのは本文だけです。

ペイロードには、変更されたオブジェクト全体を含むfull形式と、識別子程
度だけを含め、残りを受信側がAPIから取得するthin形式があります。仕様
は両者の長短を比較しています。full形式なら、受信側は追加のAPI呼び出
しを省けます。thin形式なら生成・送信するデータが少なく、柔軟で、後の
変更にも余裕があります。thin形式をfull形式に広げることはできても、そ
の逆はできないためです。また、必要なデータを受信側が明示的に要求する
ので、データへのアクセスを監査可能にできます。いずれの場合も、仕様は
ペイロードを小さく、通常は20
kB未満に抑えるよう勧めています。Stripeもthin形式を提供し、推奨として
います。

なぜ重要なのか

Webhookがなければ、別の場所での変更を知る必要があるシステムは、ポー
リングで繰り返し問い合わせることになります。たいていは何も起きていな
いという答えを受け取り、変更があっても次の問い合わせまで分かりませ
ん。Webhookは、この向きを逆にします。イベントを知っているサービス
が、その発生時に1回呼び出します。決済事業者、コードホスティングサー
ビス、メール事業者は、この方法で、それらを利用するシステムに結果を通
知します。

逆向きにすることには負担があり、その大半は受信側が負います。エンドポ
イントは、インターネット上の誰でもPOSTできる公開URLです。届いたリク
エストだけでは送信者は分からないため、仕様は、安全な実装では真正性の
検証を必須としています。配信は、受信側が2xxを返すか配信方針に従って
断念するまで再試行されるので、同じイベントが複数回届くことがありま
す。Stripeも、エンドポイントに重複が届く場合があると警告しています。
順序も保証されません。Stripeは、イベントが生成された順に届くことを保
証しないと明記しています。

一方、送信側は試行を続けなければなりません。仕様は、指数バックオフと
ランダムなジッターを使い、数日にわたって再試行する日程を推奨していま
す。例では10回試行し、最後は最初の試行から75時間35分5秒後です。
Stripeは、本番モードで最大3日間再試行します。その期間内に受信側が復
旧すれば、自動的に追い付きます。期間を過ぎた場合でも、Stripeではイベ
ント作成後15日間は手動で、CLIなら30日間は再送できます。長期間失敗が
続く場合、仕様は、メールなど別の経路で受信側に知らせ、エンドポイント
を無効にするよう勧めています。

実際の活用例

次は、仕様の形式に従った配信ヘッダーです。識別子、タイムスタンプ、署
名は仕様自身の例の値ですが、`Host`の値とパスは架空のものです。

```http
POST /webhooks/billing HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1674087231
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

本文は次のとおりです。同じ仕様のthin形式のペイロードを、ここでは読み
やすく整形しています。仕様は、実際に送る際には余分な空白を省くよう推
奨しています。

```json
{
  "type": "contact.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "1f81eb52-5198-4599-803e-771906343485"
  }
}
```

`v1`という接頭辞は、共通鍵を使う署名を表します。イベント識別子、タイ
ムスタンプ、本文をピリオドでつなぎ、エンドポイント固有のシークレット
を使ってHMAC-SHA256を計算します。識別子とタイムスタンプも本文と一緒
に署名されるため、どちらも署名を無効にせずに変更することはできませ
ん。仕様は`v1a`で示す非対称鍵のed25519署名も認めており、送信側と受信
側の安全管理を別々の主体が担う場合に推奨しています。

GitHubも配信にHMAC-SHA256で署名し、`X-Hub-Signature-256`に、
`sha256=`を先頭に付けた16進表記のダイジェストを入れます。また、検証
器をテストするためのシークレット、ペイロード、署名を公開しています。
次のPythonの検証器は、その例との一致を確認したものです。

```python
import hashlib
import hmac


def verify(body: bytes, secret: str, header: str) -> bool:
    mac = hmac.new(secret.encode("utf-8"), body, hashlib.sha256)
    expected = "sha256=" + mac.hexdigest()
    return hmac.compare_digest(expected, header)


secret = "It's a Secret to Everybody"
header = (
    "sha256=757107ea0eb2509fc211221cce984b8a"
    "37570b6d7586c22c46f4379c8b043e17"
)
print(verify(b"Hello, World!", secret, header))  # True
print(verify(b"Hello, World! ", secret, header))  # False
```

本文の末尾に空白が1つ増えるだけで検証に失敗します。
`hmac.compare_digest`は、文字列の不一致が先頭付近にあっても末尾付近
にあっても、同じ時間で比較します。GitHubの文書は、単純な`==`で署名を
比較しないよう求めています。その後の適切なハンドラーは、決まった順序
で処理します。生のバイト列を読み、そのバイト列そのものに対する署名を
検証し、送信側が試行時刻も署名しているなら、それが十分に新しいことを
確認します。次に、このイベント識別子を受信済みか確認し、イベントを
キューに入れ、2xxを返します。本来の処理は、その後に行います。Stripe
は、会計システムで顧客の請求書を支払い済みにする前に200を返す例を挙
げています。

このサイトの実績には、受信側としてWebhookを扱うプロジェクトが2つあり
ます。Stripeとアプリ内購入の利用権限管理では、サブスクリプションは、
同じWebhookが2回届くことや、順序が入れ替わって届くことにも耐えなけれ
ばなりません。自動切り替えと配信記録を備えたメールシステムでは、受信
Webhookが、各メール事業者がメッセージをどう扱ったかを通知します。
送った内容と返ってきた通知の両方を、送信ログと配信イベントのテーブル
に記録します。

問題が起きるところ

署名が一度も一致しない。
よくある原因は、受信側のフレームワークがJSON本文を解析し、コードが
HMACを計算する前に再びシリアライズすることです。仕様も、これを非常に
よくある失敗としています。JSONのシリアライズ方法は実装ごとに異なり、
余計な空白が1つあるだけで署名が無効になります。同じ理由で、Stripeも
生の本文を必要とし、手を加えると検証に失敗すると警告しています。
GitHubはさらに、エンドポイントの前にあるプロキシやロードバランサー
も、ペイロードやヘッダーを変更してはならず、ペイロードはUTF-8として
扱うべきだとしています。何かが解析する前に、届いたバイト列そのものか
ら署名を計算します。

同じイベントが2回届く。
再試行でもネットワークの障害でも重複は起きます。仕様では、同じイベン
トの再試行では`webhook-id`を変えず、冪等キーとして使います。例では、
識別子をRedisに5分間保存しています。Stripeは、処理したイベントIDを記
録し、処理済みなら再び処理しないよう求めています。また、1つの出来事
から別々のEventオブジェクトが2つ生成されることもあり、その場合は
`data.object`のオブジェクトIDとイベントの種類を組み合わせて識別でき
るとしています。GitHubの`X-GitHub-Delivery`ヘッダーも、再配信時に同
じ値を保ちます。2回目の配信では何も変わらない、冪等な処理にします。

記録された配信が再生される。
有効な署名は有効なままなので、1回の配信を傍受した攻撃者は、それを再
送できます。そのため、タイムスタンプにも署名します。仕様は、許容範囲
を外れた`webhook-timestamp`を拒否するよう求めています。Stripeのライ
ブラリーでは、設定を変えなければ許容範囲は5分です。Stripeは、0を指定
すると検査自体が無効になると警告し、サーバーの時計を正確に保つために
NTPを推奨しています。Stripeも仕様も、再試行のたびに新しいタイムスタ
ンプを付けるため、古さを測る起点は元のイベントではなく、その試行で
す。遅れた試行なら、それでも許容範囲を外れることがあります。受信済み
識別子を少なくとも許容期間と同じ長さだけ保管すれば、期間内の再生は重
複として検出できます。

イベントの到着順が入れ替わる。
Stripeの例では、サブスクリプションの作成によって
`customer.subscription.created`、`invoice.created`、`invoice.paid`が
生成され、課金があれば`charge.created`も生成されますが、この順で届く
保証はありません。Stripeのスナップショットイベントの`created`フィー
ルドは秒単位で、複数イベントが同じタイムスタンプを持つことがありま
す。Stripeは、これを順序の判定や重複検出に使わないよう求めています。
堅牢な方法は、イベントを何かが変わったという通知として扱い、動作する
前にAPIからオブジェクトの現在の状態を取得することです。

ハンドラーが遅すぎる。
GitHubは10秒以内の2xxを要求し、それを過ぎると接続を終了して配信失敗
と数えます。仕様が推奨するリクエストのタイムアウトは、15秒から30秒の
間です。本来の処理をハンドラー内でそのまま行うと、タイムアウトし、送
信側が再試行して、処理が2回走ります。StripeもGitHubもキューを推奨し
ています。Stripeは、すべてのサブスクリプションが更新される月初の集中
を例に挙げています。

成功は2xxだけ。
仕様でもStripeでも、それ以外は3xxも含めて失敗です。そのため、エンド
ポイントをリダイレクト先に移しただけでは、登録URLを更新するまで毎回
失敗します。仕様は、一部のコードごとに送信側が取るべき対応を定めてい
ます。`410
Gone`はエンドポイントの無効化、429、502、504は送信を遅くする合図で、
`retry-after`ヘッダーも次の試行時刻に反映すべきものです。

送信側にとってURLは敵対的な入力になる。
顧客は好きなURLを入力でき、送信側のサーバーがそこを呼び出します。仕
様は、Webhookシステムは特にサーバーサイドリクエストフォージェリ
（SSRF）の影響を受けやすいとしています。内部アドレスを指すURLによっ
て、送信側に自身のネットワーク内を呼び出させる攻撃です。対策として、
Stripeのsmokescreenのように内部IPアドレスを除外するプロキシにすべて
のWebhookリクエストを通し、Webhookワーカーを内部サービスに到達できな
いプライベートサブネットで動かすよう勧めています。

参考資料

  * Standard Webhooks仕様 —
バージョン1.0.0。ペイロードの構造、署名方式、ヘッダー、再試行の日
程、ステータスコードの扱い、SSRF。

  * WebhookエンドポイントでStripeイベントを受信する —
thin形式とスナップショット形式のペイロード、再試行、重複と順序の入れ
替わり、再生への対策。

  * Webhook利用のベストプラクティス —
GitHubの推奨事項。イベントを絞ること、Webhookのシークレット、HTTPS、
10秒以内の応答、再配信、`X-GitHub-Delivery`。

  * Webhook配信の検証 — `X-Hub-Signature-256`、定時間比較、検証器を
照合するためのテスト例。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/webhook/	engineer.company	70
