Webhookとは何ですか?
Webhookは、特定のイベントが発生した際にCorgeaが外部システムにリアルタイムで通知を送る自動化されたHTTPコールバックです。更新を確認するためにAPIを継続的にポーリングする代わりに、Webhookは何かが起きた瞬間に指定されたエンドポイントに直接イベントデータをプッシュします。主な利点
- リアルタイム通知 - セキュリティ上の問題が検出されたり、ステータス変更があったり、スキャン完了した際に即時の更新を受け取る
- 自動化 - Slack、Zapier、カスタムアプリケーションなどの外部ツールでワークフローをトリガーします
- 効率 - APIをポーリングする必要がなく、イベントが発生した際にデータをあなたにプッシュします
- 柔軟性 - 関心のあるイベントのみを購読し、プロジェクト、ステータス、またはスケジュールされたスキャンで絞り込む
- 信頼性 - 組み込みの再試行ロジックと配信追跡により通知が確実に届きます
サポートイベントタイプ
Corgeaは以下のイベントでWebhookをサポートしています: 問題イベント:issue.status_changed- 問題のステータスが更新されたときにトリガー(例:オープン→修正済み)issue.assigned- 問題がチームメンバーに割り当てられたときにトリガーされます
sla.violation- 日々のSLAジョブが、修復やエスカレーション期限を過ぎて1つ以上のSASTまたはSCAの問題を検出したときにトリガーされます( SLA管理のSLAごとに設定)
scan.started- セキュリティスキャン開始時にトリガーされますscan.completed- スキャンが成功裏に完了したときにトリガーされますscan.failed- スキャン中にエラーが発生した場合にトリガーされますscheduled_scan.daily_report- スケジュールされたスキャン実行が完了した際に毎日トリガーされ、過去24時間以内のすべての実行で新たな問題が要約されます。メールとペイロードスキーマについては 通知 を参照してください。
scan.started、 scan.completed、 scan.failed)には data.message が含まれます。これはSlackやZapier、その他のチャットツールに入力できる短いプレーンテキストの要約です。また、トリアージフィールド( pull_request_id、 scan_url、 true_positive_count、 project_name、 status)も含まれます。Slack Workflow Builder(Type = Slackとhooks.slack.com/triggers/...)では、Corgeaがscan.started、scan.completed、scan.failed、webhook.testのみをトップレベルのキーにフラット化します。Slackでネストされたdata.*をマッピングするとHTTP 400が発生します。同じSlack Webhookのその他のイベントタイプでは、ネストされたエンベロープが維持されます。詳細はSlackを参照してください。user.login- ユーザーが正常にログインした際にトリガーされますuser.login_failed- ユーザーのログイン試行が失敗したときにトリガーされます
Webhookの仕組み
Webhookのライフサイクル
イベントが起こる
Webhookがトリガーされました
フィルタリング適用
ペイロード製造
Type = Slack + triggers/ URL)では、Corgeaは scan.* と webhook.test のみHTTPボディをフラット化します。他のイベントは入れ子状のままです。HTTP POSTリクエスト
リトライロジック
配信記録済み
ペイロード構造
デフォルトでは、Webhookのペイロードは標準化されたネストされたエンベロープ(Zapier / その他)に従います。スキャンライフサイクルイベントにはdata.message およびトリアージフィールドが含まれます:
summary.total_issues 、削除されていないすべての問題(誤検知やコード品質を含む)をカウントします。 true_positive_count は message およびスキャンイベントフィルターで使用されるトリアージカウントです。
true_positive_countは誤検知でない削除されていないセキュリティ検出結果をカウントします(スキャンUIと同じ論理で、status=false_positive、hold_reason=false_positive、detected_by=code-quality除外)。scan.completedメッセージのオプション(N with fixes)接尾辞は、誤検知でない検出結果の中でのみ修正をカウントします(スキャン上のすべての問題ではありません)。
**ペイロードsla.violation**例(SLA管理の日次ジョブより):
sla.violationに登録するか、SLA管理フォームからWebhookを添付してください(既存のWebhookは自動で購読されます)。
**ペイロードscheduled_scan.daily_report**例:
セキュリティ機能
HMAC署名検証
HMAC署名検証
- CorgeaはWebhookを作成する際に自動的にシークレットキーを生成します
- 各リクエストには、ペイロードのHMAC-SHA256ハッシュを含む
X-Corgea-Signatureヘッダーが含まれています - シークレットキーで署名を確認し、WebhookがCorgeaから発信されているか確認する
カスタムヘッダー
カスタムヘッダー
- エンドポイントに求められるヘッダー(例:認証トークン)を含める
- Webhook設定時にカスタムヘッダーを設定する
HTTPS必須
HTTPS必須
- すべてのWebhook URLはHTTPSを使用する必要があります(通常はポート443)
- URLはURL内に認証情報を埋め込んではならない
- プライベート、ループバック、リンクローカル、予約済み、またはマルチキャストアドレスに解決される宛先は拒否される(SSRF保護)
- オペレーターはオプションでホストを制限
WEBHOOK_ALLOWED_HOSTS設定
自動再試行ロジック
- 初回試行 + 2回の再試行 = 合計3回の試み
- 指数的バックオフ:2秒、再試行間4秒
- タイムアウト:リクエストごとに10秒
- 自動一時停止:10回連続で失敗すると、Webhookは自動的に一時停止されます
各Webhookに送信されるヘッダー
Webhookのセットアップ

前提条件
ステップバイステップのセットアップ
統合へナビゲーション
- CorgeaでIntegrationsを開きます
- Automation IntegrationsでWebhooksを開きます

基本設定の設定

- 名称:明確なラベル(例:「Slack通知」や「本番スキャンアラート」など)
- Webhook URL:あなたのHTTPSエンドポイント
- タイプ:
Slack— Slackワークフロービルダーまたは受信Webhookの送信先Zapier— ザピア・キャッチフックOther— カスタムエンドポイント
イベント購読

- 問題ステータス変更
- 割り当てられた問題
- SLA違反(
sla.violation) - スキャン開始/完了/失敗
- ユーザーログイン / ユーザーログイン失敗
- Scheduled Scan Daily Report(
scheduled_scan.daily_report)
フィルターの設定(オプション)

scan.* イベント用)- プルリクエスト/マージリクエストのみスキャン —
pull_request_idなしのスキャンはスキップ - 誤検知でない検出結果がある完了済みスキャンのみ —
true_positive_countが0の場合はscan.completedをスキップします(scan.failedとscan.startedには影響しません)
- 無効のままにすると、すべてのプロジェクトからイベントを受信
- フィルターを有効にすると、Webhookを選択したプロジェクトに限定
sla.violationでは、ペイロード内のいずれかのプロジェクトが一致するとWebhookを送信
issue.status_changed用)- 空欄にすると、すべてのステータス変更を受信
- または、
fixedやfalse_positiveなどのステータスに限定
scan.*イベント用)- 無効のままにすると、手動とスケジュールの両方を含むすべてのスキャンを受信
- 有効にすると、選択したスケジュールスキャンだけを受信
カスタムヘッダーとボディの追加(オプション)
Jira 自動化
Jira 自動化
- Jiraで「Incoming webhook」トリガー付きの自動化ルールを作成します
- Jiraが提供したシークレットトークンをコピーする
- Corgeaのヘッダー値として追加する
Slack
Slack
https://hooks.slack.com/triggers/...)を推奨します。Type = Slackでは、Corgeaがscan.*とwebhook.testをフラット化します。message、pull_request_id、scan_url、true_positive_count、companyをマッピングしてください。ネストされたdata.*はマッピングしないでください(SlackからHTTP 400が返されます)。その他のイベントタイプはフラット化されません。詳細はSlackを参照してください。受信Webhook(https://hooks.slack.com/services/...)には、レンダリングされたJSONがトップレベルの空でない文字列 text フィールドを持つカスタムボディが必要です。 {"text": "{{message}}"} はスキャンライフサイクルイベントや scheduled_scan.daily_reportにのみ使用してください。Microsoft Teams
Microsoft Teams
https://xxx.webhook.office.com/webhookb2/xxx/IncomingWebhook/xxx)ベアラートークンによるカスタムAPI
ベアラートークンによるカスタムAPI
Splunk HEC
Splunk HEC
APIキーによるカスタムAPI
APIキーによるカスタムAPI
PagerDuty
PagerDuty
routing_key を使用しています。PagerDuty Events APIエンドポイントをご利用ください: https://events.pagerduty.com/v2/enqueueZapier
Zapier
- Webhookリクエストボディ用のJSONオブジェクトテンプレートをオプションで提供
- 空欄のままにしてCorgeaのデフォルトのペイロード構造を使う
- サポートされたプレースホルダー:
{{payload}}(完全なデフォルトペイロードオブジェクト){{time}}(Unixの秒){{timestamp}}(ISO 8601タイムスタンプ){{event_type}}{{event_id}}{{message}}(スキャンライフサイクルイベントと日次レポートで利用可能)
- レンダリングされたテンプレートが無効なJSONの場合、配信が失敗し、webhook履歴にエラーが表示されます
保存して有効化
- クリック Webhook作成
- ポップアップからシークレットキーをコピーする — Corgeaは一度だけ表示します

- クリック シークレットキーを保存しました
- Webhookがアクティブでイベントの受信を開始する
Webhookをテスト
- Webhookを開き、「テスト・Webhook」 クリック
- エンドポイントが2xxレスポンスを返すことを確認する
- Slack Workflow Builderの場合:テスト中に変数をマッピングできるよう、トップレベル
messageが空でないフラットボディとサンプルトリアージキー(pull_request_id、scan_url、true_positive_countなど)を備えてください。ネストのみのワークフロービルダー設定はサポートされていません。
Webhook署名の検証
X-Corgea-Signature ヘッダーを検証します。- Python
- Node.js
ユースケース
1.リアルタイムSlack通知
シナリオ:重大度の高い問題が見つかった場合はSlackのセキュリティチームに通知します セットアップ:- Slackワークスペース内でSlackの受信WebhookURLを作成する
- Corgeaでは、以下のようなWebhookを作成します。
- タイプ:
Slack - URL:あなたのSlackWebhookURL
- イベント:
scan.completed - プロジェクトフィルター:重要な制作プロジェクト
- タイプ:
2.重大な問題に対する自動チケット作成
シナリオ:重大な問題が検出された際にJira/Linearで自動的にチケットを作成します セットアップ:- チケットを作成するZapierのzapやカスタムエンドポイントを作成する
- Corgeaでは、以下のようなWebhookを作成します。
- イベント:
scan.completed、issue.status_changed - ステータスフィルター:ステータスのみ
open(重複チケットを避けるため) - プロジェクトフィルター:制作プロジェクト
- イベント:
3.リスク受容ワークフロー統合
シナリオ:セキュリティ問題が「承認済みリスク」とマークされている場合、JiraまたはLinearで自動的に承認済みリスクを記録する セットアップ:- ドキュメントチケットを作成するエンドポイントまたはZapier統合を作成する
- Corgeaでは、以下のようなWebhookを作成します。
- イベント:
issue.status_changed - ステータスフィルター:状態のみ
accepted_risk - プロジェクトフィルター:すべてのプロジェクトまたは特定の高コンプライアンスプロジェクト
- イベント:
- 統合を以下に設定する:
- リスク受容を文書化したチケットを作成する
- 問題の詳細(分類、ファイルパス、緊急性)を含める
- 「リスク受け入れ」ラベルが付いたタグ
- セキュリティリードにレビューを割り当てる
4.カスタムダッシュボード統合
シナリオ:内部ダッシュボードにリアルタイムのセキュリティ指標を表示する セットアップ:- Webhookデータを受け取りダッシュボードを更新するエンドポイントを構築する
- Corgeaでは、以下のようなWebhookを作成します。
- イベント:すべてのスキャンイベントと問題イベント
- フィルターなし(すべて受信)
5.マルチチームルーティング
シナリオ:異なるプロジェクト通知を異なるチームにルーティングする セットアップ:- 各チームごとに別々のWebhookを作成する:
- バックエンドチーム Webhook: プロジェクトフィルター = バックエンドプロジェクト、Slackチャンネル #backend セキュリティ
- フロントエンドチームのWebhook: プロジェクトフィルター = フロントエンドプロジェクト、Slackチャネル #frontend セキュリティ
- DevOps Team Webhook: プロジェクトフィルター = インフラストラクチャプロジェクト、Slack チャンネル #devops セキュリティ
6.コンプライアンス報告
シナリオ:すべてのセキュリティ検出結果を自動的にコンプライアンスシステムにログ登録します セットアップ:- コンプライアンスデータベースに書き込みを行うエンドポイントを作成する
- Corgeaでは、以下のようなWebhookを作成します。
- イベント:
scan.completed - 全プロジェクト
- 監査トレイル用にWebhookの配信履歴を保存
- イベント:
トラブルシューティング
Webhook配信履歴の閲覧
Webhookの履歴を開く

配信ログにアクセス
配信の詳細を確認

- イベントの種類とタイムスタンプ
- HTTPステータスコード
- リクエスト/レスポンスの詳細
- エラーメッセージ(あれば)
- 再試行
よくある問題と解決策
Webhookがイベントを受け取らない
Webhookがイベントを受け取らない
- Webhookが一時停止または非アクティブ
- イベントサブスクリプションが設定されていません
- プロジェクト、ステータス、スケジュールスキャンのフィルターによってイベントが除外されている
- エンドポイントが2xxステータスコードを返さない
- Webhookの状態を確認する - アクティブ(一時停止していない)を確認
- イベントのサブスクリプションが選ばれているか確認する
- フィルターのレビュー - プロジェクト、ステータス、またはスケジュールされたスキャンフィルターを一時的に解除してテストする
- エンドポイントログでリクエストの受信を確認する
- 「テストWebhook」ボタンを使ってWebhookをテストする
Webhookが自動的に一時停止
Webhookが自動的に一時停止
- 配信履歴でエラーの詳細を確認する
- エンドポイントのURLが正しく、アクセス可能であることを確認する
- エンドポイントが2xxステータスコードを返すことを確認する
- Corgeaのリクエストをブロックするファイアウォールやセキュリティルールがないか確認
- 根本原因を修正した後、Webhookを手動で再有効化する
- 「Test Webhook」を使って動作を確認し、再有効化する
Webhookコールが多すぎる
Webhookコールが多すぎる
- ステータスフィルターを使用します。
issue.status_changedでは、必要なステータス(例:fixedとfalse_positive)のみに絞り込みます - プロジェクトフィルターを使う :特定の重要なプロジェクトのみ購読
- スケジュールスキャンフィルター:スキャンイベントでは、Webhookをトリガーするスケジュール済みスキャンを選択します
- イベント購読を減らす:不要なイベントの購読を解除する
- レート制限の実装:エンドポイントでレート制限またはキューイングを実装します
署名検証の失敗
署名検証の失敗
- 誤ったシークレットキー
- 誤った署名検証ロジック
- 文字エンコーディングの問題
- Corgeaのシークレットキーを正確に使っていることを確認する
- HMAC-SHA256アルゴリズムを使用していることを確認してください
- 検証には生のリクエストボディ(解析されていないJSON)を使用する
- 送信側と受信側の両方でUTF-8エンコーディングを確認する
- タイミング攻撃に耐性のある比較として、
hmac.compare_digest()(Python)またはcrypto.timingSafeEqual()(Node.js)を使用する
エンドポイントのタイムアウト
エンドポイントのタイムアウト
- 即時に応答:直ちに200 OKを返し、その後非同期で処理する
- キューを使用:バックグラウンド処理のためにWebhookペイロードをキューに追加する
- 処理を最適化:Webhookハンドラーの処理を高速化する
- リソースを増強:エンドポイントのインフラをスケールアップする
重複イベント
重複イベント
- 同じイベントに複数のWebhookがサブスクライブ
- 遅延成功後の再試行ロジックのトリガー
- 重複したWebhook構成の確認
- 冪等性を確保するために
event_idフィールドを使用し、処理済みのイベントIDを保存して重複をスキップする - エンドポイントに冪等キーを実装する
ペイロードの欠落データ
ペイロードの欠落データ
- Webhookの配信履歴でペイロード全体を確認する
- データが存在しない場合(例:問題に担当者が割り当てられていない場合)、一部のフィールドが
nullになることがあります - ハンドラコードにnullチェックを実装する
- イベント固有のペイロード構造をデリバリー履歴で参照する
Webhook統計の取得
Webhookのパフォーマンス指標を見る:- Integrations → Webhooksに移動します
- 各Webhookの統計を見る:
- 総配信数:Webhookコールの総数
- 成功した配信:2xx回のレスポンスを返した呼び出し
- 配信失敗:失敗またはタイムアウトした呼び出し
- 成功率:成功した配信の割合
- 連続失敗:現在の失敗記録
- 最後のトリガー:Webhookが最後に送信した時刻
手動再試行
Webhookの配信に失敗した場合は、手動で再試行できます。- Webhooks → Integrations → History
- 失敗した配信を見つける
- Retryをクリックする
- 新しい配信試行が作成され、直ちに送信されます
配信履歴のエクスポート
コンプライアンス対応やデバッグのために、Webhookの配信履歴をエクスポートできます。- Integrations → Webhooks → Historyに移動する
- フィルター(日付範囲、イベントタイプ、ステータス、Webhook)を適用する
- エクスポート をクリックしてCSVをダウンロードします
- エクスポートを以下に利用します:
- コンプライアンス監査
- パフォーマンス分析
- デバッグパターン
- 問題解決の追跡
テストのヒント
ライブ開始前に
ライブ開始前に
- ペイロードの検査に webhook.site または リクエストビン を使用します
- まず低ボリュームプロジェクトでテストします
- 最初の数日間の配信成功率を監視する
- 自社システム内でWebhookの障害に対するアラートを設定する
デバッグチェックリスト
デバッグチェックリスト
- WebhookのURLが正確かつアクセス可能であること
- エンドポイントが10秒以内に2xxステータスコードを返す
- ファイアウォールはCorgeaのリクエストを許可しています
- イベントのサブスクリプションが選定されます
- フィルターが正しく設定されているか(またはテストのために取り外されている)
- 署名検証が機能します(シークレットを使用する場合)
- Webhookがアクティブ(一時停止されていない)
ペイロードの例
- 問題ステータス変更
- スキャン開始
- スキャン完了
- スキャン失敗
- 割り当てられた問題
- SLA違反
- ユーザーログイン
- ユーザーログイン失敗
- Scheduled Scan Daily Report
よくある質問
複数のイベントタイプで同じWebhookURLを使えますか?
複数のイベントタイプで同じWebhookURLを使えますか?
X-Corgea-Event ヘッダーと event_type フィールドが表示されます。Webhookは何個作れる?
Webhookは何個作れる?
もしエンドポイントがダウンしたらどうなりますか?
もしエンドポイントがダウンしたらどうなりますか?
実際のイベントをトリガーせずにWebhookをテストすることはできますか?
実際のイベントをトリガーせずにWebhookをテストすることはできますか?
message とトリアージキー(pull_request_id、 scan_url、 true_positive_count、 company)が含まれています。 company_id も従来のテストクライアント向けに(同じ値で)含まれています。PRスキャンの失敗や完了したPRスキャンの検出結果だけ通知できますか?
PRスキャンの失敗や完了したPRスキャンの検出結果だけ通知できますか?
scan.failedとscan.completedを登録してください。検出結果のフィルターはscan.failedには適用されません。Webhookは認証に対応していますか?
Webhookは認証に対応していますか?
X-Corgea-Signature)。宛先固有の認証トークン用のカスタムヘッダーも追加できます。Webhookを特定のブランチにフィルタリングできますか?
Webhookを特定のブランチにフィルタリングできますか?
Webhookのペイロードは暗号化されていますか?
Webhookのペイロードは暗号化されていますか?
Webhookの配信ログはどのくらいの期間保存されますか?
Webhookの配信ログはどのくらいの期間保存されますか?
手動でWebhookを再試すことはできますか?
手動でWebhookを再試すことはできますか?
WebhookはどのIPアドレスから Corgea 送っているのでしょうか?
WebhookはどのIPアドレスから Corgea 送っているのでしょうか?
ご質問や問題がある場合 連絡 Corgeaサポート
