Webhook署名検証とは｜業務システム連携で確認したい受信処理

署名検証で何を確かめ、何を別に判断するか

Webhook署名検証は、受信内容と共有した秘密情報から計算した値を、送信側の署名と照合する処理です。GitHubは、通知をさらに処理する前に署名を検証し、GitHubから送信されたことと改ざんされていないことを確認するよう案内しています。たとえばリポジトリ更新を契機に社内文書を取り込む場合、受信直後にRAGの索引更新へ進むのではなく、検証を通った通知だけを後続へ渡す構造にします。署名の確認を、処理完了後の監査ログだけで代替しないことが判断の出発点です。[1]

ただし、正規の通知であることと、その内容を業務アプリで実行してよいことは別の判断です。本稿では、署名確認後に対象組織、連携設定、イベント種別、更新先を照合する構成を提案します。たとえば共有リポジトリから届く通知でも、取り込み対象外の文書を別部署の検索領域へ登録しないようにします。AIへ渡す文章は外部入力として扱い、文章内の指示によって権限や処理先を変更しない設計にします。署名の成功を、個人情報の利用可否や利用者の閲覧権限まで認める根拠にしないことが重要です。

• 署名確認より前に、AI呼び出しや業務データの更新が動かないか。
• 連携設定と更新先の組織・検索領域を対応付けているか。
• 受信内容を、アプリの権限判断や実行指示と混同していないか。

署名対象の本文と秘密情報をどう扱うか

GitHubでは、Webhookのシークレットとペイロード内容を使ったHMACの値が、X-Hub-Signature-256ヘッダーにsha256=付きで送られます。受信側は同じシークレットで期待値を計算し、定時間比較に対応する手段で照合します。公式資料は通常の等価演算子で比較しないこと、文字コードを指定する実装ではUTF-8を扱うことも示しています。JSONとして同じ意味でも、再生成した本文が署名対象と同一とは限りません。本稿では、本文の解析や整形より前に検証用データを確保する実装を提案します。[1]

実装確認では、Webフレームワークの自動解析、プロキシ、文字コード処理のどこで本文が変わるかを追います。たとえば受信JSONをオブジェクトに変換してから文字列へ戻す構成では、空白や文字表現が変わる可能性を確認対象にします。シークレットについて、GitHubは十分なランダム性を持つ値を選び、安全に保存し、コードへの埋め込みやリポジトリへの登録を避けるよう案内しています。本稿では、開発環境と本番環境の参照先を分け、検証失敗のログにも値を出さない運用を提案します。[1]

• 署名計算に使う本文を、解析・再生成後のJSONで置き換えていないか。
• 日本語や改行を含む入力でも、検証経路を確認しているか。
• シークレットの参照先、更新権限、ログへの出力有無を確認したか。

タイムスタンプと重複通知をどう区別するか

署名が一致する通知でも、それが新しい通知か、以前受け取った通知の再送かは別に考えます。今回のGitHub資料は、X-GitHub-Deliveryを使って配送を識別し、リプレイ対策に利用することを案内しています。また、再配送を要求した場合、この値は元の配送と同じになると明記しています。一方、提示資料からは署名対象のタイムスタンプや許容時間幅を確認できません。そのため、GitHub通知を独自の時間幅だけで拒否する方式を、公式仕様として説明することはできません。[2]

本稿では、連携先ごとに時刻情報の有無、署名対象への包含、遅延時の扱いを調べ、確認できた仕様だけを採用する方針を提案します。受信側で記録した時刻は運用状況の把握に使い、それだけで送信時刻の真正性を判断しません。重複対策では、連携設定と配送識別子を組み合わせて処理記録を作り、同時に届いた通知が二重登録されない仕組みを検討します。たとえば文書の取り込み通知を二度受けても、同じ対象の索引更新を無制限に重ねず、記録済みの状態に応じて次の動作を選べる形にします。

• タイムスタンプの意味と署名対象への包含を公式仕様で確認したか。
• 重複判定のキーに、連携先や環境の違いを含めているか。
• 同じ通知が同時に届く場合も、二重処理を抑える方法があるか。

受信応答とAI処理の完了をどう分けるか

GitHubは受信から10秒以内の2XX応答を求め、それを超えると接続を終了し配送失敗と扱うと説明しています。また、キューで非同期に処理する方法を紹介しています。この期限はGitHubの条件であり、外部API全般の共通値ではありません。AIによる文書分類やRAGの索引更新を受信リクエスト内で完了させようとすると、外部処理の待ち時間が応答へ影響します。本稿では、必要な検証と処理対象の保存を受信経路に置き、時間のかかる処理は別の実行経路へ渡す構成を提案します。[2]

応答の意味も決めておく必要があります。本稿では、受信成功と業務処理完了を別の状態として管理することを提案します。署名不一致、必要項目の不足、保存先の障害を同じ「処理失敗」にまとめず、後続へ渡せたかを区別します。特に保存できていないのに受理済みと応答すると、復旧後に処理すべき記録が残らない構成になり得ます。採用する応答コードや再送への影響は連携先の仕様で確認し、検証できない通知を成功扱いにしてAI処理へ流す回避策は取らない設計にします。

• 受理済みと業務処理完了を、画面や監視で区別できるか。
• 保存に失敗した経路で、実際にどの応答を返すか決めたか。
• 未対応イベントを無視する場合も、理由を追跡できるか。

再配送と業務上の再実行をどう管理するか

GitHubは、受信サーバーの停止後に取り逃したWebhookを再配送することと、処理前にイベント種別・アクションを確認することを案内しています。ただし、今回の資料だけでは再配送のすべての手順や自動再送条件までは確定できません。本稿では、通知を受け直す再配送と、受理済みの仕事を動かし直す再実行を別の操作として設計することを提案します。これにより、配送は受理できたがAI処理だけ失敗した場合に、入口の通知をむやみに作り直さず、失敗した仕事を対象に復旧できます。[2]

たとえば索引更新の途中で外部APIが停止した場合は、保存済みの処理対象と進行状態を基に、どこから再開するかを判断します。本稿では、待機中、実行中、完了、失敗などの状態と、実行履歴を分けて残す設計を提案します。完了済み通知の再配送では副作用を繰り返さず、失敗済みなら担当者が対象と理由を確認して再実行する、といった分岐を定めます。また、後続APIの資格情報は署名用シークレットと分離し、文書取得や更新に必要な権限だけを検討します。受信できることを、任意のAPI操作を許す理由にはしません。

• 再配送と再実行の操作、対象、履歴を区別しているか。
• 途中まで成功した処理を、どこから再開するか決めたか。
• 後続APIの実行権限と資格情報の管理先が明確か。

公開前の確認表で何を試すか

公開前は、正しい通知が通ることだけでなく、拒否や保留が必要な入力で副作用が起きないことを確認します。本稿では、個人情報を含まないテストデータを使い、入力条件、期待結果、観測結果を一組で記録する方法を提案します。受信側の単体テストだけでは、本文が中継経路で変わる問題や、保存先の障害時の動きまでは見えない場合があります。そのため、アプリ内部の検証と、本番に近い受信経路を通す確認を分けます。表は確認計画の例であり、いずれの項目も実施済みを意味しません。

本番保守で何を記録し、どう引き継ぐか

本稿では、保守用ログに受信日時、連携設定の識別子、検証結果、配送識別子、処理状態を残し、本文全体の常時保存は必要性を判断してから採用することを提案します。個人情報を扱うアプリでは、通知本文をそのままエラーログへ出すと、業務データとは別の場所にも管理対象が増えます。本文の調査保存が必要な場合は、閲覧者、保存期間、削除方法を先に定めます。通常の監視では署名失敗と後続処理失敗を分け、秘密情報や本文を開かなくても異常の場所を絞れる記録を目指します。

引き継ぎ資料には、受信URLの用途、連携設定の管理者、秘密情報の保管先、変更権限、停止と復旧の手順を記載します。本稿では、秘密情報の値そのものを手順書へ書かず、権限を持つ担当者が参照する方法を残す運用を提案します。更新時に新旧の秘密情報を併用できるかは、連携先と受信実装の確認事項です。未確認のまま切替可能と扱いません。また、監視の通知先だけでなく、誰が業務への影響を判断し、誰が再実行を承認するかを決めることで、技術担当者だけでは復旧を決められない場面にも備えます。

• 通常ログに本文やシークレットが混入していないか。
• 秘密情報の変更方法と切替時の確認事項を記録したか。
• 停止判断、業務影響の確認、復旧承認の担当が決まっているか。

よくある質問

署名検証の担当者が不在でも公開してよいですか。

本稿では、代わりに設定を確認し、異常時に停止判断できる担当を定めてから公開することを提案します。担当者名だけでなく、必要な権限と手順へのアクセスを確認します。代理担当もおらず、署名失敗を把握する経路もない場合は、公開範囲を限定するか延期する判断が必要です。

連携先に確認用の環境がない場合はどうしますか。

まずローカルのテストデータで検証ロジックと失敗経路を確認します。ただし、それだけで実際の配送経路まで確認済みとは扱いません。本稿では、本番側に業務更新を行わない限定的な受信先を用意できるか検討し、許可されたテスト通知で接続を確認する案を提案します。できない確認は未確認として公開判断に残します。

外部サービスの都合で署名を検証できない間だけ、期限付きで受け入れてもよいですか。

期限があることだけでは、通知の真正性を確認できるようにはなりません。本稿では、未検証の入力を通常の処理経路へ流すのではなく、後続処理を止めた保留領域に置く案を提案します。保留自体も受信容量や個人情報の管理が必要です。例外の責任者、終了条件、保留データの扱いを決められなければ、受信停止も選択肢になります。

連携を一時休止する場合、通知を受け続けるべきですか。

休止中に発生した変更を復帰後に反映する必要があるかで分けます。必要なら保留できる量、保存期間、復帰時の処理順を検討します。不要なら送信側の購読停止も候補ですが、停止期間の通知を後から取得できるとは断定できません。再取得方法を公式仕様で確認し、休止前に業務側と復帰時の扱いを合意する設計を提案します。

参考・関連資料

• [1] Validating webhook deliveries - GitHub Docs ↗
• [2] Best practices for using webhooks - GitHub Docs ↗

公式資料の確認日：2026-10-19。業務例は説明用で、顧客の実績ではありません。編集：株式会社N2i。執筆にAI支援を使用し、別のAIによる出典・品質確認に合格した記事を公開する方針です。