Webhook署名シークレットの漏えい疑いがあるとき、受信エンドポイント、署名検証、再送、ログ、ローテーションをどう確認するか。開発者・SaaS管理者向けの初動チェックリスト。
冒頭要約
Webhook署名シークレットは、GitHub、Stripe、SlackなどのSaaSから届く通知が正規の送信元か、途中で改ざんされていないかを受信側で確認するための秘密情報です。 漏えい疑いがある場合、まず見るべきなのは「誰がその値を知っているか」だけではありません。どのWebhookエンドポイントに使われ、どの環境・ログ・CI/CD・SaaS設定に残っているかを切り分ける必要があります。 初動では、攻撃再現や検証用リクエストの送信ではなく、対象一覧、署名検証ログ、受信失敗、再送履歴、secretの失効・再発行計画を揃えます。
この記事は防御・確認・初動対応を目的にしています。署名を偽造する手順、payload、PoC、第三者環境への送信テスト、探索クエリは扱いません。調査メモやチケットにもsecret値そのものは貼らず、識別子、対象、時刻、対応内容で記録します。
Webhook署名シークレットとは
Webhook は、SaaSや外部サービスのイベントを自社システムへHTTP通知する仕組みです。たとえば、決済完了、Issue作成、ビルド完了、チャット通知、ユーザー作成などをきっかけに、受信側のアプリが処理を実行します。
ここで重要になるのが Webhook Secret と Webhook Signature Verification です。Webhookの送信元サービスと受信側が共有するsecretを使い、リクエスト本文やタイムスタンプを署名します。受信側は署名を検証し、正規の通知か、本文が変わっていないか、古いリクエストの再利用ではないかを判断します。
つまり、Webhook署名シークレットは「Webhookのパスワード」そのものではありません。しかし、漏えいすると偽の通知や改ざん検知の失敗につながる可能性があるため、APIキーやOAuthクライアントシークレットと同じく、シークレット管理とローテーションの対象として扱う必要があります。
読者別の影響
| 読者 | 影響 | まず見る場所 |
|---|---|---|
| 開発者 | 受信処理の誤実行、注文・課金・通知・CI処理の誤作動 | Webhook受信コード、環境変数、デプロイ設定、エラーログ |
| SaaS管理者 | どのアプリ・環境・組織でsecretが使われているか把握しにくい | SaaSのWebhook設定、監査ログ、アプリ連携一覧 |
| 情報システム担当者 | 退職者・委託先・古いBotがsecretを保持している可能性 | 権限棚卸し、Secret Manager、チケット、共有ドキュメント |
| CSIRT・インシデント対応 | 偽通知・再送・異常処理があったかを判断する必要がある | 受信ログ、署名検証失敗ログ、下流システムの操作ログ |
| 事業・業務担当 | 決済、受注、顧客通知など業務処理に影響する可能性がある | 影響サービス、処理件数、再処理要否、顧客影響 |
まず確認すること：Webhook署名シークレット漏えい時のチェックリスト
漏えい疑いでは、secret値の真偽を試すより先に、対象範囲を狭めます。以下の順番で確認すると、開発者とSaaS管理者の認識を合わせやすくなります。
| 項目 | 確認内容 | 記録すること |
|---|---|---|
| 1. 検知元 | どこで漏えい疑いを検知したか。リポジトリ、CIログ、チャット、チケット、画面共有、端末ログを分ける。 | 検知元、検知時刻、発見者、対象リンク |
| 2. secretの種類 | GitHub、Stripe、Slack、社内SaaS、決済、CI/CDなど、どのWebhookのsecretかを特定する。 | サービス名、環境、本番/検証、所有チーム |
| 3. 受信エンドポイント | secretが保護しているURL、アプリ、リージョン、環境、冗長構成を確認する。 | URLの識別子、アプリ名、環境、管理者 |
| 4. 保管場所 | Secret Manager、環境変数、CI/CD、Kubernetes Secret、SaaS設定、IaC、古いドキュメントを確認する。 | 正規の保管先、不適切な保管先、削除予定 |
| 5. 署名検証 | 受信側で署名検証が有効か、検証失敗時に処理を止めているか確認する。 | 検証方式、有効/無効、失敗時動作 |
| 6. 再送・重複処理 | Webhookの再送、重複通知、タイムアウト時に二重処理しない設計か確認する。 | 再送件数、処理ID、重複排除の有無 |
| 7. ログ | 署名検証失敗、想定外の送信元、異常なイベント種別、急増した失敗を確認する。 | 期間、件数、送信元、イベント種別 |
| 8. 下流影響 | 受信後に何が実行されるか。支払い、権限変更、デプロイ、通知、チケット作成を確認する。 | 下流処理、影響件数、再処理要否 |
Webhookは、ユーザー一覧やOAuthアプリ一覧だけでは見落とされやすい継続アクセスです。SaaS権限棚卸しチェックリスト と合わせて、Bot、Webhook、APIトークン、外部共有を同じ台帳で管理すると、退職者対応や委託終了時にも漏れにくくなります。
初動対応：やること、やらないこと、記録すべきこと
やること
- 対象Webhookと受信エンドポイントを特定する。
- secret値そのものをチケットやチャットに貼らず、識別子と保存先だけを記録する。
- 署名検証が有効か、失敗時に処理を止めているかを確認する。
- 受信ログ、署名検証失敗ログ、下流処理ログを保全する。
- 旧secretと新secretを一時的に併用できるか、サービス公式手順を確認する。
- 新secretを発行し、受信側設定を更新し、成功/失敗率を監視する。
- 旧secretを削除または無効化し、再送キューや失敗イベントを確認する。
- 不要なWebhook、所有者不明のWebhook、退職者・委託先が作成したWebhookを停止する。
やらないこと
- 漏えいした可能性のあるsecret値を第三者サービス、AIチャット、チケット、メールへ貼り付けない。
- 偽通知を作って本番エンドポイントへ送信しない。
- 最新コミットやログから値を消しただけで完了にしない。
- 署名検証失敗を一時的に無視して本番復旧を急がない。
- どの下流処理が動くか確認せずにWebhookを一括停止しない。
記録すべきこと
| 記録項目 | 例 |
|---|---|
| 対象 | サービス名、Webhook名、環境、受信エンドポイント、所有チーム |
| 検知 | 検知元、検知時刻、検知者、該当リポジトリ/ログ/チケット |
| 判断 | 署名検証の有無、漏えい場所、公開範囲、本番影響、下流処理 |
| 対応 | 新secret発行、設定反映、デプロイ、旧secret削除、Webhook停止 |
| 監視 | 署名検証失敗件数、受信成功率、再送件数、下流処理失敗 |
| 再発防止 | Secret Manager移行、Secret Scanning、権限棚卸し、ローテーション周期 |
ローテーション手順：止めないための実務順序
Webhook署名シークレットのローテーションは、単に値を差し替える作業ではありません。送信元SaaS、受信アプリ、下流処理、監視の順番がずれると、正規通知を落としたり、二重処理したりする可能性があります。
| フェーズ | 実施内容 | 完了条件 |
|---|---|---|
| 準備 | 対象Webhook、受信アプリ、環境変数、Secret Manager、デプロイ手順を確認する。 | 変更対象とロールバック条件が明確 |
| 並行検証 | 公式機能で可能な範囲で、新旧secretの受け入れ期間を設ける。 | 新secretで署名検証が成功する |
| 反映 | 受信側設定、環境変数、CI/CD、Kubernetes Secret、SaaS設定を更新する。 | 本番通知の成功率が通常範囲 |
| 監視 | 署名検証失敗、再送、タイムアウト、下流処理失敗を確認する。 | 重大な受信失敗や二重処理がない |
| 旧secret削除 | 旧secretを無効化し、古い設定やドキュメントから削除する。 | 旧secretの利用箇所が残っていない |
| 事後記録 | 変更時刻、担当者、影響有無、残リスク、次回見直し日を記録する。 | 監査・説明に使える記録がある |
サービスによって、複数secretの併用可否、署名ヘッダー、タイムスタンプ許容範囲、再送仕様は異なります。GitHub、Stripe、Slackなどの公式ドキュメントを確認し、自社の実装が「公式が想定する検証方式」とずれていないかも見ます。
判断基準：危険度とエスカレーション条件
| 危険度 | 条件 | 対応 |
|---|---|---|
| 高 | 本番Webhookのsecretが公開リポジトリ、CIログ、外部チャット、委託先環境に露出した可能性がある | 重大インシデント候補として扱い、secretローテーション、ログ保全、下流影響確認を即時実施 |
| 高 | 署名検証が無効、または検証失敗でも処理が続く | 受信処理の一時制限、修正、再処理判断、CSIRT/責任者へエスカレーション |
| 中 | 検証環境のsecretだが、本番と同じ下流SaaSやデータに接続している | 本番相当として影響範囲を確認し、ローテーションと接続先点検を実施 |
| 中 | 所有者不明、退職者作成、長期未更新のWebhookがある | 退職者アカウント対応 やSaaS棚卸しに組み込み、所有者と期限を決める |
| 低 | secretは正規保管先のみ、署名検証有効、漏えい疑いが誤検知と説明できる | 根拠を記録し、次回ローテーション・Secret Scanning設定を確認 |
よくある誤解
「Webhook URLを知っているだけでは危険ではない」
URLだけでは処理できない設計が望ましい一方、署名検証が無効ならURLの露出だけでリスクが上がります。URL、secret、署名検証、下流処理をセットで判断します。
「ログからsecretを消せば終わり」
ログ削除は再発防止の一部です。値が外部に見えた可能性があるなら、旧secretの失効、再発行、影響サービス確認、下流処理ログの確認まで必要です。
「検証環境だから後回しでよい」
検証環境でも、本番相当のSaaS、決済、GitHub、CI/CD、顧客データへ接続している場合があります。環境名ではなく、secretが到達できる処理で優先度を決めます。
「SaaS管理画面で新しいsecretを作れば完了」
受信側アプリ、環境変数、デプロイ、監視、旧secret削除、再送確認が残ります。変更管理として扱わないと、正常なWebhookを落とす原因になります。
関連用語・関連ページ
| 目的 | ページ |
|---|---|
| Webhookの基礎を確認する | Webhookとは、Webhook Secretとは、Webhook署名検証とは |
| secret管理を整理する | Secrets Managementとは、Secrets Rotationとは、Secret Scanningとは |
| 漏えい初動を作業化する | GitHub secret leak対応チェックリスト、GitHubトークン漏えい対応テンプレート |
| SaaS全体の棚卸しへ広げる | SaaS権限棚卸しチェックリスト、SaaS権限棚卸しの進め方 |
| 事故対応の基本を学ぶ | インシデントレスポンス入門、GitHub Secret Scanningアラート初動対応 |
| 手を動かして練習する | GitHub secret leak 初動ミニCTF |
公式情報・参考情報
- GitHub Docs: Validating webhook deliveries — GitHub Webhookのsecret設定と受信側検証の公式手順。
- Stripe Docs: Resolve webhook signature verification errors — Webhook signing secret、署名ヘッダー、検証失敗時の確認観点。
- Slack Docs: Verifying requests from Slack — Signing Secret、タイムスタンプ、署名検証の公式説明。
- OWASP Cheat Sheet: Secrets Management — secretの保管、ローテーション、露出時対応の一般的な原則。
まとめ
Webhook署名シークレットの漏えい疑いでは、「secretを変える」だけでなく、対象Webhook、受信エンドポイント、署名検証、再送、下流処理、ログ、所有者を同時に確認します。Webhookは外部SaaSから自社処理を動かす入口です。GitHub、Stripe、Slackなど公式ドキュメントの検証方式に沿って、ローテーション、監視、旧secret削除、再発防止まで一つの初動対応として扱うことが重要です。
