Webhookの仕組み — 「何か起きたら知らせて」を安全に受け取る

ひよこ

更新されたか、何度も見に行かないといけない？

ペンギン先生

相手が対応していればWebhookで「変化が起きたら、このURLへ知らせて」と設定できるよ。受け取るサービスがHTTPの通知を扱う。何度も問い合わせるポーリングとは向きが違うんだ。

ひよこ

普通のAPIが、逆向きになった感じ？

ペンギン先生

入口としては分かりやすいね。ただしWebhookは通知の仕組みで、すべてのAPIを逆にしたものではない。GitHubのようにPOSTでイベントを送るサービスがあるけれど、形式や条件は提供元の仕様を読むよ。

ひよこ

URLがあれば、誰の通知でも受け取っていい？

ペンギン先生

自分の用途に合うイベントかを確かめ、本物の通知を検証してから処理しよう。GitHubでは共有した秘密値と受け取った本文から計算するHMAC署名を使える。URLを秘密にすることだけには頼らないんだ。

ひよこ

署名が同じなら、新しい通知だと分かる？

ペンギン先生

本文の改ざん検査と、古い通知を繰り返すリプレイの対策は別だよ。GitHubの配送ID等を使って、同じ配送を処理済みか記録する。署名を検証したことだけで重複がなくなるわけではないんだ。

ひよこ

受け取ったら、重い作業も全部終えて返事する？

ペンギン先生

提供元の時間制限に間に合うように、検証した仕事を確実に受け付けてから返し、重い処理はキュー等で後に進める設計がある。受け付け前に成功を返すと、その後の失敗で失うおそれがあるよ。

ひよこ

返事をしなかったら、必ず自動で再送される？

ペンギン先生

サービスによって違うよ。GitHubは失敗した配送を自動で再送しないので、履歴から手動でやり直すか、再送する仕組みを用意する。ほかのサービスも条件や期間を確かめよう。

ひよこ

更新と削除の通知は、起きた順に必ず来る？

ペンギン先生

順番の保証を仕様で確かめよう。IDや時刻があっても、届く順だけで状態を決めると誤る場合がある。必要なら対象の現在状態をAPIで確認するなど、イベントの用途に合わせるんだ。

ひよこ

最初に何を試すと分かりやすい？

ペンギン先生

下の小さな署名実験を見てみよう。同じ本文は検証でき、1文字変えた本文は合わない。実際の公開受信サーバーを作る前に、受信本文をそのまま使う意味をつかめるよ。

まずは、「聞きに行く」と「知らせてもらう」を分ける

更新を知るために毎回尋ねるのがポーリング、相手が変化に合わせて通知するのがWebhookです。たとえばリポジトリの更新を受けて、別のサービスへ仕事を渡すときに使えます。

通知を受けたことと、作業が終わったことは別です。図では通知を検証して受け付けるところまでを示し、後の作業は分けています。

小さく試す：本文を変えると署名は合わなくなる

Python 3が使えるなら、次をsignature-demo.pyに保存し、python signature-demo.pyで実行してみましょう。秘密値はこの場で作る練習用の値です。GitHubへ設定したり、外部へ送ったりする例ではありません。

import hashlib
import hmac
import secrets

secret = secrets.token_bytes(32)
body = b'{"action":"created"}'
received = "sha256=" + hmac.new(
    secret, body, hashlib.sha256
).hexdigest()

def verify(raw_body, signature):
    expected = "sha256=" + hmac.new(
        secret, raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

print(verify(body, received))
print(verify(b'{"action":"deleted"}', received))

True
False

実際のGitHubの通知では、受け取ったX-Hub-Signature-256と、保存した秘密値・受信した元の本文のバイト列から計算した署名を比較します。JSONを読み直して並べ替えた本文ではなく、受信本文をそのまま使います。署名がない場合も受け付けません。

練習では送信側と受信側を同じプログラムで表しています。本番では秘密値を安全に管理し、毎回ランダムに作り直すのではなく、送信側と受信側で対応する値を使います。コードやURL、公開リポジトリへ秘密値を置きません。

受付の返事と、後の仕事を分ける

GitHubは2XXのHTTP応答を10秒以内に返すことを案内しています。これはGitHubの条件であり、どのサービスにも同じ10秒を当てはめるものではありません。

検証し、必要なイベントだけを確実に受け付けてから応答します。重い仕事をキューへ渡す場合、保存や登録が失敗しても成功応答を返す設計にしないことが大切です。後の作業の失敗は、受付のHTTP応答だけでは分かりません。

もう少し詳しく：重複・再送・順番

• 重複：GitHubではX-GitHub-Deliveryを使い、同じ配送を処理済みか管理できます。再配送でも同じIDなので、途中で失敗した仕事を再試行できる状態管理と合わせます。
• 再送：GitHubは失敗を自動再配送しません。履歴から再配送するか、APIを使った仕組みで補います。失敗履歴と未完了の仕事を確認する入口を用意しましょう。
• 順番：届いた順だけで最新状態を上書きせず、イベントの保証と用途を調べます。必要な場合はAPIから対象の状態を確認します。
• 接続方式：WebhookはHTTPのイベント通知です。WebSocketやSSEのような継続した接続の方式とは役割が違い、HTTPでも接続が再利用される場合はあります。

🐧 ペンギン先生のまとめ：「Webhook」って出てきたら「何か起きたら、決めたURLへ知らせてもらう仕組み」と思えばだいたいOK！

受け付けた仕事はメッセージキュー、送り方の保護はHTTPとHTTPSの違いへ進むとつながります。

参考資料

• GitHub：Best practices for using webhooks — HTTPS・受付の時間と応答・イベント・配送ID
• GitHub：Validating webhook deliveries — 元の本文のHMAC署名・秘密値・定数時間の比較
• GitHub：Handling failed webhook deliveries — 失敗は自動再送されない・履歴と再配送