> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgea.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook
> Corgeaから外部システムへのHTTPコールバックの自動化
## Webhookとは何ですか?
Webhookは、特定のイベントが発生した際にCorgeaが外部システムにリアルタイムで通知を送る自動化されたHTTPコールバックです。更新を確認するためにAPIを継続的にポーリングする代わりに、Webhookは何かが起きた瞬間に指定されたエンドポイントに直接イベントデータをプッシュします。
### 主な利点
* **リアルタイム通知** - セキュリティ上の問題が検出されたり、ステータス変更があったり、スキャン完了した際に即時の更新を受け取る
* **自動化** - Slack、Zapier、カスタムアプリケーションなどの外部ツールでワークフローをトリガーします
* **効率** - APIをポーリングする必要がなく、イベントが発生した際にデータをあなたにプッシュします
* **柔軟性** - 関心のあるイベントのみを購読し、プロジェクト、ステータス、またはスケジュールされたスキャンで絞り込む
* **信頼性** - 組み込みの再試行ロジックと配信追跡により通知が確実に届きます
### サポートイベントタイプ
Corgeaは以下のイベントでWebhookをサポートしています:
**問題イベント:**
* `issue.status_changed` - 問題のステータスが更新されたときにトリガー(例:オープン→修正済み)
* `issue.assigned` - 問題がチームメンバーに割り当てられたときにトリガーされます
**SLAイベント:**
* `sla.violation` - 日々のSLAジョブが、修復やエスカレーション期限を過ぎて1つ以上のSASTまたはSCAの問題を検出したときにトリガーされます( [SLA管理](sla_management)のSLAごとに設定)
**スキャンイベント:**
* `scan.started` - セキュリティスキャン開始時にトリガーされます
* `scan.completed` - スキャンが成功裏に完了したときにトリガーされます
* `scan.failed` - スキャン中にエラーが発生した場合にトリガーされます
* `scheduled_scan.daily_report` - スケジュールされたスキャン実行が完了した際に毎日トリガーされ、過去24時間以内のすべての実行で新たな問題が要約されます。メールとペイロードスキーマについては [通知](notifications#daily-scan-report) を参照してください。
スキャンライフサイクルイベント(`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](slack)を参照してください。
**ユーザー認証イベント:**
* `user.login` - ユーザーが正常にログインした際にトリガーされます
* `user.login_failed` - ユーザーのログイン試行が失敗したときにトリガーされます
***
## Webhookの仕組み
### Webhookのライフサイクル
Corgeaで何かが起こる(例:スキャン完了、問題ステータスが変わるなど)
システムはそのイベントタイプに登録されているすべてのWebhookを識別します
プロジェクト、ステータス、スケジュールスキャン、PRのみ、完了後フィルターがWebhookをトリガーさせるかどうかを判断します
デフォルトでは、標準化されたJSONエンベロープはイベント詳細で構築されます(設定されていればカスタムボディテンプレートが使われます)。Slack Workflow Builder(`Type = Slack` + `triggers/` URL)では、Corgeaは `scan.*` と `webhook.test` のみHTTPボディをフラット化します。他のイベントは入れ子状のままです。
ペイロードはセキュリティヘッダーとともにWebhookのURLに送信されます
リクエストが失敗した場合、指数関数的なバックオフで自動再試行が行われます
すべての試みは配信履歴に記録され、トラブルシューティングが行われます
### ペイロード構造
デフォルトでは、Webhookのペイロードは標準化されたネストされたエンベロープ(Zapier / その他)に従います。スキャンライフサイクルイベントには `data.message` およびトリアージフィールドが含まれます:
```json webhook-payload.json theme={null}
{
"event_id": "550e8400-e29b-41d4-a716-446655440000",
"event_type": "scan.completed",
"timestamp": "2025-01-15T14:30:00.000Z",
"data": {
"company": "company-uuid",
"scan_id": "scan-uuid",
"run_id": "run-12345",
"project": {
"id": "project-uuid",
"name": "My Application"
},
"project_name": "My Application",
"branch": "feature/auth",
"engine": "corgea-blast",
"scan_type": "full",
"status": "completed",
"pull_request_id": "42",
"scan_url": "https://app.corgea.app/project/project-uuid/?scan_id=scan-uuid",
"true_positive_count": 5,
"summary": {
"total_issues": 12,
"issues_with_fixes": 7,
"issues_without_fixes": 5,
"true_positive_count": 5,
"true_positive_issues_with_fixes": 3
},
"message": "Scan completed for My Application (PR #42): 5 true-positive findings (3 with fixes). View: https://app.corgea.app/project/project-uuid/?scan_id=scan-uuid",
"scheduled_scan_ids": ["scheduled-scan-uuid"],
"processed_at": "2025-01-15T14:30:00.000Z",
"created_at": "2025-01-15T14:00:00.000Z"
}
}
```
`summary.total_issues` 、削除されていないすべての問題(誤検知やコード品質を含む)をカウントします。 `true_positive_count` は `message` およびスキャンイベントフィルターで使用されるトリアージカウントです。
| イベント | 例 `data.message` |
| ---------------- | --------------------------------------------------------------------------------- |
| `scan.started` | `Scan started for My Application (PR #42).` |
| `scan.completed` | `Scan completed for My Application (PR #42): 5 true-positive findings. View: ...` |
| `scan.failed` | `Scan failed for My Application (PR #42): Scanner timed out. View: ...` |
`true_positive_count`は誤検知でない削除されていないセキュリティ検出結果をカウントします(スキャンUIと同じ論理で、`status=false_positive`、`hold_reason=false_positive`、`detected_by=code-quality`除外)。`scan.completed`メッセージのオプション`(N with fixes)`接尾辞は、誤検知でない検出結果の中でのみ修正をカウントします(スキャン上のすべての問題ではありません)。
**Slack Workflow Builder**：`Type = Slack`でURLが`hooks.slack.com/triggers/...`の場合、Corgeaは`scan.*`と`webhook.test`に対して**フラットな**ボディをPOSTします（トップレベルの`message`、`pull_request_id`、`scan_url`、`true_positive_count`、`company`など）。Slackではネストされた`data.*`のマッピングがサポートされず、HTTP 400が発生します。このWebhookのスキャン以外のイベントは**フラット化されません**。詳細は[Slack](slack)を参照してください。
\*\*ペイロード`sla.violation`\*\*例(SLA管理の日次ジョブより):
```json sla-violation-payload.json theme={null}
{
"event_id": "550e8400-e29b-41d4-a716-446655440001",
"event_type": "sla.violation",
"timestamp": "2025-01-15T14:30:00.000Z",
"data": {
"company": "1",
"sla": {
"id": 3,
"rule_type": "code",
"urgency": ["CR", "HI"],
"remediation_days": 7,
"escalation_days": 3
},
"notification_type": "remediation",
"issue_kind": "SAST",
"issue_count": 5,
"summary_message": "Plain-text summary (same style as email body)...",
"projects": [
{
"id": "project-uuid",
"name": "My Application",
"url": "https://app.corgea.com/project/project-uuid",
"issue_count": 5,
"urgency_counts": {
"Critical": 2,
"High": 3
}
}
]
}
}
```
| フィールド | 説明 |
| ------------------- | --------------------------------------------------- |
| `notification_type` | `remediation` または `escalation` |
| `issue_kind` | `SAST` または `SCA` |
| `sla.rule_type` | `code` (SAST)または `sca` (依存関係) |
| `projects` | 対象プロジェクトごとに1件のエントリー;Webhook **プロジェクトフィルターに使用されました** |
**Integrations → Webhooks**の`sla.violation`に登録するか、[SLA管理](sla_management)フォームからWebhookを添付してください(既存のWebhookは自動で購読されます)。
\*\*ペイロード`scheduled_scan.daily_report`\*\*例:
```json scheduled-scan-daily-report-payload.json theme={null}
{
"event_id": "550e8400-e29b-41d4-a716-446655440002",
"event_type": "scheduled_scan.daily_report",
"timestamp": "2025-01-15T14:30:00.000Z",
"data": {
"title": "Corgea Daily Scan Report",
"company": "1",
"company_name": "Acme Security",
"total_new_issues": 7,
"message": "Daily scan report for Acme Security: 7 new issues detected across 2 scan runs.",
"scan_runs": [
{
"scheduled_scan_name": "Weekly Production Scan",
"project": "Payments API",
"new_issue_count": 4,
"scan_url": "https://www.corgea.app/scans/scan-uuid"
}
]
}
}
```
企業管理者は、このイベントが設定→通知 **→会社のデフォルト**からWebhookに送信されるかどうかを制御できます。
Webhookの設定時に**Custom Body**を指定すると、Corgeaはデフォルトのペイロード構造ではなく、レンダリングされたJSONオブジェクトを送信します。
`scheduled_scan.daily_report` イベントは同じエンベロープを使用しますが、独自の `data` スキーマを持っています。詳細は [ペイロードの例](#payload-examples) を参照してください。
### セキュリティ機能
* CorgeaはWebhookを作成する際に自動的にシークレットキーを生成します
* 各リクエストには、ペイロードのHMAC-SHA256ハッシュを含む `X-Corgea-Signature` ヘッダーが含まれています
* シークレットキーで署名を確認し、WebhookがCorgeaから発信されているか確認する
* エンドポイントに求められるヘッダー(例:認証トークン)を含める
* Webhook設定時にカスタムヘッダーを設定する
* すべてのWebhook URLはHTTPSを使用する必要があります（通常はポート443）
* URLはURL内に認証情報を埋め込んではならない
* プライベート、ループバック、リンクローカル、予約済み、またはマルチキャストアドレスに解決される宛先は拒否される(SSRF保護)
* オペレーターはオプションでホストを制限 `WEBHOOK_ALLOWED_HOSTS` 設定
### 自動再試行ロジック
Webhookの配信が失敗した場合、Corgeaは自動的に次の戦略で再試行します:
* **初回試行** + **2回の再試行** = 合計3回の試み
* **指数的バックオフ**:2秒、再試行間4秒
* **タイムアウト**:リクエストごとに10秒
* **自動一時停止**:10回連続で失敗すると、Webhookは自動的に一時停止されます
### 各Webhookに送信されるヘッダー
```text webhook-headers.txt theme={null}
Content-Type: application/json
X-Corgea-Event: issue.status_changed
X-Corgea-Delivery:
X-Corgea-Timestamp:
X-Corgea-Signature:
User-Agent: Corgea-Webhooks/1.0
```
***
## Webhookのセットアップ
### 前提条件
Corgeaアカウントの管理者権限または統合管理権限
POSTリクエストを受け入れるWebhookエンドポイントURL
HTTPSエンドポイント(セキュリティに必要)
### ステップバイステップのセットアップ
* Corgeaで**Integrations**を開きます
* **Automation Integrations**で**Webhooks**を開きます
単独の**Slack**と**Zapier**の項目は非推奨です。新しい設定では**Webhooks**を使用してください。既存のSlack/Zapier連携は引き続き動作します。テストまたは削除するには、**View All**を開きます。
* **名称**:明確なラベル(例:「Slack通知」や「本番スキャンアラート」など)
* **Webhook URL**:あなたのHTTPSエンドポイント
* **タイプ**:
* `Slack` — Slackワークフロービルダーまたは受信Webhookの送信先
* `Zapier` — ザピア・キャッチフック
* `Other` — カスタムエンドポイント
Slackでは、Workflow BuilderのURL（`hooks.slack.com/triggers/...`）を推奨します。Corgeaは、これらの送信先に対する`scan.*`と`webhook.test`をフラット化します。ネストされた`data.*`ではなく、トップレベルの`message`をマッピングしてください。スキャン以外のイベントはネストされたままです。Incoming Webhooks（`hooks.slack.com/services/...`）は、レンダリング後のJSONにトップレベルで空でない文字列の`text`フィールドを含むCustom Bodyを設定しない限り拒否されます。`{"text": "{{message}}"}`は、スキャンライフサイクルイベントと`scheduled_scan.daily_report`だけで使用できます。詳細は[Slack](slack)を参照してください。
通知を受け取るイベントを有効にします。複数選択できます。
* 問題ステータス変更
* 割り当てられた問題
* 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.*`イベント用）
* 無効のままにすると、手動とスケジュールの両方を含むすべてのスキャンを受信
* 有効にすると、選択したスケジュールスキャンだけを受信
**カスタムヘッダー**
Webhookの送信先で必要なヘッダーを追加してください。各サービスには異なる要件があります:
**必要ヘッダー:**
```text theme={null}
X-Automation-Webhook-Token:
```
**トークンの入手方法:**
1. Jiraで「Incoming webhook」トリガー付きの自動化ルールを作成します
2. Jiraが提供したシークレットトークンをコピーする
3. Corgeaのヘッダー値として追加する
[Jira Webhookのドキュメント](https://support.atlassian.com/cloud-automation/docs/configure-the-incoming-webhook-trigger-in-atlassian-automation/)
**カスタムヘッダーは** 不要 — 認証はSlackのURLにあります。
Workflow BuilderのURL（`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](slack)を参照してください。
受信Webhook(`https://hooks.slack.com/services/...`)には、レンダリングされたJSONがトップレベルの空でない文字列 `text` フィールドを持つカスタムボディが必要です。 `{"text": "{{message}}"}` はスキャンライフサイクルイベントや `scheduled_scan.daily_report`にのみ使用してください。
**カスタムヘッダーは不要** Teams Webhook URL自体に認証が含まれています。
TeamsのWebhookURLを貼り付けるだけです(フォーマット: `https://xxx.webhook.office.com/webhookb2/xxx/IncomingWebhook/xxx`)
Teamsの受信Webhookはカスタムヘッダーを検証しません。セキュリティはWebhookのURLを非公開に保つことで提供されます。
[Teams Webhook ドキュメント](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
**ヘッダー:**
```text theme={null}
Authorization: Bearer
```
JWTやOAuthトークンを使うREST APIでよく使われます。
**ヘッダー:**
```text theme={null}
Authorization: Splunk
```
Splunk HTTP Event Collector（HEC）エンドポイントにWebhookイベントを送信する場合に使用します。
**ヘッダー(1つを選び):**
```text theme={null}
X-API-Key:
```
または
```text theme={null}
Authorization: ApiKey
```
シンプルなAPIキー認証にはよく使われます。
**カスタムヘッダーは不要** PagerDuty Events API v2は認証にJSONペイロードの `routing_key` を使用しています。
PagerDuty Events APIエンドポイントをご利用ください: `https://events.pagerduty.com/v2/enqueue`
PagerDutyはカスタムヘッダーを検証しません。認証はリクエスト本体のrouting\_keyを通じて行われます。
[PagerDuty Webhook ドキュメント](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview)
**カスタムヘッダーは不要** - ZapierのWebhookURLはURL自体に認証が含まれています。
「ZapierによるWebhooks」トリガーを作成し、提供されたURLを使います。
ZapierのCatch Hookはデフォルトでカスタムヘッダーを検証しません。セキュリティはWebhookのURLを非公開に保つことで提供されます。必要に応じてZap内にヘッダー検証ロジックを追加することもできます。
[Zapier Webhookのドキュメント](https://zapier.com/help/create/code-webhooks/trigger-zaps-from-webhooks)
もしサービスがここに記載されていない場合は、サービスのwebhookや受信webhookのドキュメントで必要なヘッダーを確認してください。
**重要:** Corgeaは設定したカスタムヘッダーを送信しますが、すべてのwebhook宛先がそれを検証するわけではありません。Slack、Teams、Zapierのようなサービスはヘッダー検証ではなくシークレットURLに依存しています。カスタムヘッダーは、目的のサービスが実際に必要または検証している場合(JiraやカスタムAPIなど)にのみ追加してください。
**カスタムボディ**
* Webhookリクエストボディ用のJSONオブジェクトテンプレートをオプションで提供
* 空欄のままにしてCorgeaのデフォルトのペイロード構造を使う
* サポートされたプレースホルダー:
* `{{payload}}` (完全なデフォルトペイロードオブジェクト)
* `{{time}}` (Unixの秒)
* `{{timestamp}}` (ISO 8601タイムスタンプ)
* `{{event_type}}`
* `{{event_id}}`
* `{{message}}`（スキャンライフサイクルイベントと日次レポートで利用可能）
* レンダリングされたテンプレートが無効なJSONの場合、配信が失敗し、webhook履歴にエラーが表示されます
* クリック **Webhook作成**
* ポップアップからシークレットキーをコピーする — Corgeaは一度だけ表示します
ダイアログを閉じる前にシークレットキーを保存してください。その後は再表示できません。ローテーションが必要ならサポートに連絡してください。
* クリック **シークレットキーを保存しました**
* Webhookがアクティブでイベントの受信を開始する
* Webhookを開き、「テスト・Webhook」 **クリック**
* エンドポイントが2xxレスポンスを返すことを確認する
* Slack Workflow Builderの場合:テスト中に変数をマッピングできるよう、トップレベル `message` が空でないフラットボディとサンプルトリアージキー(`pull_request_id`、 `scan_url`、 `true_positive_count`など)を備えてください。ネストのみのワークフロービルダー設定はサポートされていません。
### Webhook署名の検証
作成時に表示されたシークレットキーを使って、各リクエストの `X-Corgea-Signature` ヘッダーを検証します。
```python verify-signature.py theme={null}
import hmac
import hashlib
def verify_webhook_signature(payload, signature, secret):
"""Verify Corgea webhook signature"""
expected_signature = hmac.new(
secret.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected_signature, signature)
# In your webhook handler:
if not verify_webhook_signature(request.body, request.headers['X-Corgea-Signature'], SECRET_KEY):
return HttpResponse(status=403) # Reject invalid signatures
```
```javascript verify-signature.js theme={null}
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expectedSignature),
Buffer.from(signature)
);
}
```
***
## ユースケース
### 1.リアルタイムSlack通知
**シナリオ**:重大度の高い問題が見つかった場合はSlackのセキュリティチームに通知します
**セットアップ**:
* Slackワークスペース内でSlackの受信WebhookURLを作成する
* Corgeaでは、以下のようなWebhookを作成します。
* タイプ: `Slack`
* URL:あなたのSlackWebhookURL
* イベント: `scan.completed`
* プロジェクトフィルター:重要な制作プロジェクト
**結果**:スキャン完了すると #security チャンネルに即時通知が届きます
***
### 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配信履歴の閲覧
**Integrations** → **Webhooks**に移動します。
**History**または**Delivery Log**をクリックします。
次の情報を含む、すべてのWebhook配信試行を確認できます。
* イベントの種類とタイムスタンプ
* HTTPステータスコード
* リクエスト/レスポンスの詳細
* エラーメッセージ(あれば)
* 再試行
### よくある問題と解決策
**可能な原因:**
* Webhookが一時停止または非アクティブ
* イベントサブスクリプションが設定されていません
* プロジェクト、ステータス、スケジュールスキャンのフィルターによってイベントが除外されている
* エンドポイントが2xxステータスコードを返さない
**解決方法:**
1. Webhookの状態を確認する - アクティブ(一時停止していない)を確認
2. イベントのサブスクリプションが選ばれているか確認する
3. フィルターのレビュー - プロジェクト、ステータス、またはスケジュールされたスキャンフィルターを一時的に解除してテストする
4. エンドポイントログでリクエストの受信を確認する
5. 「テストWebhook」ボタンを使ってWebhookをテストする
**原因:** 10回連続の配信失敗
**解決方法:**
1. 配信履歴でエラーの詳細を確認する
2. エンドポイントのURLが正しく、アクセス可能であることを確認する
3. エンドポイントが2xxステータスコードを返すことを確認する
4. Corgeaのリクエストをブロックするファイアウォールやセキュリティルールがないか確認
5. 根本原因を修正した後、Webhookを**手動で再有効化**する
6. 「Test Webhook」を使って動作を確認し、再有効化する
**解決方法:**
1. **ステータスフィルター**を使用します。`issue.status_changed`では、必要なステータス（例：`fixed`と`false_positive`）のみに絞り込みます
2. **プロジェクトフィルター**を使う :特定の重要なプロジェクトのみ購読
3. **スケジュールスキャンフィルター**：スキャンイベントでは、Webhookをトリガーするスケジュール済みスキャンを選択します
4. **イベント購読を減らす**:不要なイベントの購読を解除する
5. **レート制限**の実装:エンドポイントでレート制限またはキューイングを実装します
**可能な原因:**
* 誤ったシークレットキー
* 誤った署名検証ロジック
* 文字エンコーディングの問題
**解決方法:**
1. Corgeaのシークレットキーを正確に使っていることを確認する
2. HMAC-SHA256アルゴリズムを使用していることを確認してください
3. 検証には生のリクエストボディ(解析されていないJSON)を使用する
4. 送信側と受信側の両方でUTF-8エンコーディングを確認する
5. タイミング攻撃に耐性のある比較として、`hmac.compare_digest()`（Python）または`crypto.timingSafeEqual()`（Node.js）を使用する
受信した署名と計算した署名の両方をログに記録して比較
**原因:** エンドポイントのレスポンスに10秒以上かかる
**解決方法:**
1. **即時に応答**:直ちに200 OKを返し、その後非同期で処理する
2. **キューを使用**:バックグラウンド処理のためにWebhookペイロードをキューに追加する
3. **処理を最適化**:Webhookハンドラーの処理を高速化する
4. **リソースを増強**:エンドポイントのインフラをスケールアップする
**ベストプラクティスパターン:**
```python webhook-handler.py theme={null}
@app.route('/webhook', methods=['POST'])
def handle_webhook():
payload = request.json
# Immediately acknowledge receipt
queue.add(process_webhook, payload)
# Return quickly
return '', 200
def process_webhook(payload):
# Do time-consuming work here
...
```
**可能な原因:**
* 同じイベントに複数のWebhookがサブスクライブ
* 遅延成功後の再試行ロジックのトリガー
**解決方法:**
1. 重複したWebhook構成の確認
2. 冪等性を確保するために`event_id`フィールドを使用し、処理済みのイベントIDを保存して重複をスキップする
3. エンドポイントに冪等キーを実装する
**冪等性パターン:**
```python idempotency.py theme={null}
processed_events = set() # Or use Redis/database
@app.route('/webhook', methods=['POST'])
def handle_webhook():
event_id = request.json['event_id']
if event_id in processed_events:
return '', 200 # Already processed
# Process event...
processed_events.add(event_id)
return '', 200
```
**解決方法:**
1. Webhookの配信履歴でペイロード全体を確認する
2. データが存在しない場合（例:問題に担当者が割り当てられていない場合）、一部のフィールドが`null`になることがあります
3. ハンドラコードにnullチェックを実装する
4. イベント固有のペイロード構造をデリバリー履歴で参照する
### Webhook統計の取得
Webhookのパフォーマンス指標を見る:
1. **Integrations** → **Webhooks**に移動します
2. 各Webhookの統計を見る:
* **総配信数**:Webhookコールの総数
* **成功した配信**:2xx回のレスポンスを返した呼び出し
* **配信失敗**:失敗またはタイムアウトした呼び出し
* **成功率**:成功した配信の割合
* **連続失敗**:現在の失敗記録
* **最後のトリガー**:Webhookが最後に送信した時刻
***
### 手動再試行
Webhookの配信に失敗した場合は、手動で再試行できます。
1. **Webhooks** → **Integrations** → **History**
2. 失敗した配信を見つける
3. **Retry**をクリックする
4. 新しい配信試行が作成され、直ちに送信されます
***
### 配信履歴のエクスポート
コンプライアンス対応やデバッグのために、Webhookの配信履歴をエクスポートできます。
1. **Integrations** → **Webhooks** → **History**に移動する
2. フィルター(日付範囲、イベントタイプ、ステータス、Webhook)を適用する
3. **エクスポート** をクリックしてCSVをダウンロードします
4. エクスポートを以下に利用します:
* コンプライアンス監査
* パフォーマンス分析
* デバッグパターン
* 問題解決の追跡
***
### テストのヒント
1. ペイロードの検査に [webhook.site](https://webhook.site) または [リクエストビン](https://requestbin.com) を使用します
2. まず低ボリュームプロジェクトでテストします
3. 最初の数日間の配信成功率を監視する
4. 自社システム内でWebhookの障害に対するアラートを設定する
* WebhookのURLが正確かつアクセス可能であること
* エンドポイントが10秒以内に2xxステータスコードを返す
* ファイアウォールはCorgeaのリクエストを許可しています
* イベントのサブスクリプションが選定されます
* フィルターが正しく設定されているか(またはテストのために取り外されている)
* 署名検証が機能します(シークレットを使用する場合)
* Webhookがアクティブ(一時停止されていない)
***
## ペイロードの例
```json issue-status-changed.json theme={null}
{
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_type": "issue.status_changed",
"timestamp": "2025-01-15T14:30:00.000Z",
"data": {
"company": "comp-uuid-1234",
"issue_id": "issue-uuid-5678",
"classification": "SQL Injection",
"urgency": "HI",
"status": "fixed",
"previous_status": "open",
"file_path": "src/controllers/user.py",
"line_num": 45,
"project": {
"id": "proj-uuid-9012",
"name": "Production API"
},
"scan_id": "scan-uuid-3456",
"url": "https://app.corgea.com/issue/issue-uuid-5678/"
}
}
```
```json scan-started.json theme={null}
{
"event_id": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
"event_type": "scan.started",
"timestamp": "2025-01-15T15:40:00.000Z",
"data": {
"company": "comp-uuid-1234",
"scan_id": "scan-uuid-7890",
"run_id": "run-12345",
"project": {
"id": "proj-uuid-9012",
"name": "Production API"
},
"project_name": "Production API",
"branch": "main",
"engine": "corgea-blast",
"scan_type": "full",
"status": "started",
"pull_request_id": "42",
"scan_url": "https://app.corgea.app/project/proj-uuid-9012/?scan_id=scan-uuid-7890",
"true_positive_count": 0,
"message": "Scan started for Production API (PR #42).",
"scheduled_scan_ids": ["scheduled-scan-uuid"],
"created_at": "2025-01-15T15:40:00.000Z"
}
}
```
```json scan-completed.json theme={null}
{
"event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"event_type": "scan.completed",
"timestamp": "2025-01-15T15:45:00.000Z",
"data": {
"company": "comp-uuid-1234",
"scan_id": "scan-uuid-7890",
"run_id": "run-12345",
"project": {
"id": "proj-uuid-9012",
"name": "Production API"
},
"project_name": "Production API",
"branch": "main",
"engine": "corgea-blast",
"scan_type": "full",
"status": "completed",
"pull_request_id": "42",
"scan_url": "https://app.corgea.app/project/proj-uuid-9012/?scan_id=scan-uuid-7890",
"true_positive_count": 5,
"summary": {
"total_issues": 8,
"issues_with_fixes": 5,
"issues_without_fixes": 3,
"severity_breakdown": {
"HI": {
"name": "High",
"count": 2
},
"ME": {
"name": "Medium",
"count": 6
}
},
"classification_breakdown": [
{
"classification": "SQL Injection",
"count": 2
},
{
"classification": "Cross-Site Scripting (XSS)",
"count": 1
}
]
},
"message": "Scan completed for Production API (PR #42): 5 true-positive findings (5 with fixes). View: https://app.corgea.app/project/proj-uuid-9012/?scan_id=scan-uuid-7890",
"scheduled_scan_ids": ["scheduled-scan-uuid"],
"processed_at": "2025-01-15T15:45:00.000Z",
"created_at": "2025-01-15T15:40:00.000Z"
}
}
```
上記のネストされたエンベロープは、ZapierとOtherが受信する形式であり、Corgeaの配信履歴にもこの形式で保存されます。Slack Workflow Builderでは、`scan.*`と`webhook.test`に限り、トリアージ用フィールドがHTTPリクエストボディの**トップレベル**キーとして送信されます（`message`、`scan_id`、`scan_url`、`pull_request_id`、`true_positive_count`、`status`、`branch`、`project_name`、`company`、`run_id`、`engine`、`scan_type`。さらに、`scan.failed`では存在する場合に`error`、`webhook.test`では`company_id`、`test`、`webhook_name`）。`summary`、`project`、`scheduled_scan_ids`、`scan_errors`、`created_at`、`processed_at`はフラット化されません。`data.message`またはトップレベルの`message`はプレーンテキストの要約です。「(N with fixes)」という接尾辞では、スキャンの全問題ではなく、誤検知でない検出結果に対する修正のみが数えられます。
```json scan-failed.json theme={null}
{
"event_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"event_type": "scan.failed",
"timestamp": "2025-01-15T15:42:00.000Z",
"data": {
"company": "comp-uuid-1234",
"scan_id": "scan-uuid-7890",
"run_id": "run-12345",
"project": {
"id": "proj-uuid-9012",
"name": "Production API"
},
"project_name": "Production API",
"branch": "main",
"engine": "corgea-blast",
"scan_type": "full",
"status": "failed",
"pull_request_id": "42",
"scan_url": "https://app.corgea.app/project/proj-uuid-9012/?scan_id=scan-uuid-7890",
"true_positive_count": 0,
"error": "Scanner timed out",
"scan_errors": null,
"message": "Scan failed for Production API (PR #42): Scanner timed out. View: https://app.corgea.app/project/proj-uuid-9012/?scan_id=scan-uuid-7890",
"scheduled_scan_ids": ["scheduled-scan-uuid"],
"created_at": "2025-01-15T15:40:00.000Z"
}
}
```
`data.message`には失敗理由（200文字を超える場合は省略）と、利用可能な場合はスキャンURLが含まれます。未加工のエラー詳細には`data.error`または`data.scan_errors`を使用します。Slack Workflow Builderでは、`error`もフラット化されたトップレベルフィールドとして利用できます。
```json issue-assigned.json theme={null}
{
"event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"event_type": "issue.assigned",
"timestamp": "2025-01-15T16:00:00.000Z",
"data": {
"company": "comp-uuid-1234",
"issue_id": "issue-uuid-5678",
"classification": "Cross-Site Scripting (XSS)",
"urgency": "ME",
"status": "open",
"assigned_to": {
"id": "user-uuid-1111",
"email": "jane.doe@company.com",
"name": "Jane Doe"
},
"previously_assigned_to": {
"id": "user-uuid-2222",
"email": "john.smith@company.com",
"name": "John Smith"
},
"project": {
"id": "proj-uuid-9012",
"name": "Production API"
},
"url": "https://app.corgea.com/issue/issue-uuid-5678/"
}
}
```
```json sla-violation.json theme={null}
{
"event_id": "f6a7b8c9-d0e1-2345-f012-345678901234",
"event_type": "sla.violation",
"timestamp": "2025-01-15T16:20:00.000Z",
"data": {
"company": "comp-uuid-1234",
"sla": {
"id": 3,
"rule_type": "sca",
"urgency": ["CR", "HI"],
"remediation_days": 14,
"escalation_days": 7
},
"notification_type": "escalation",
"issue_kind": "SCA",
"issue_count": 12,
"summary_message": "Plain-text summary of breached issues...",
"projects": [
{
"id": "proj-uuid-9012",
"name": "Production API",
"url": "https://app.corgea.com/project/proj-uuid-9012",
"issue_count": 12,
"urgency_counts": {
"Critical": 4,
"High": 8
}
}
]
}
}
```
```json user-login.json theme={null}
{
"event_id": "d4e5f6a7-b8c9-0123-def0-123456789012",
"event_type": "user.login",
"timestamp": "2025-01-15T16:10:00.000Z",
"data": {
"company": "comp-uuid-1234",
"user_id": 123,
"username": "jane.doe",
"email": "jane.doe@company.com",
"first_name": "Jane",
"last_name": "Doe",
"user_agent": "Mozilla/5.0",
"path": "/login/"
}
}
```
```json user-login-failed.json theme={null}
{
"event_id": "e5f6a7b8-c9d0-1234-ef01-234567890123",
"event_type": "user.login_failed",
"timestamp": "2025-01-15T16:12:00.000Z",
"data": {
"company": "comp-uuid-1234",
"username": "jane.doe",
"user_agent": "Mozilla/5.0",
"path": "/login/"
}
}
```
```json scheduled-scan-daily-report.json theme={null}
{
"event_id": "3282dbbb-7392-476b-8ce2-19fc1070342c",
"event_type": "scheduled_scan.daily_report",
"timestamp": "2026-05-13T12:29:53.083616+00:00",
"data": {
"title": "🐕 Corgea Daily Scan Report",
"company": "123",
"company_name": "Acme Corp",
"total_new_issues": 7,
"message": "Daily scan report for Acme Corp: 7 new issues detected across 2 scan runs.",
"scan_runs": [
{
"scheduled_scan_name": "Nightly API Scan",
"project": "api-service",
"new_issue_count": 5,
"scan_url": "https://app.corgea.com/scans/abc123"
},
{
"scheduled_scan_name": "Nightly Frontend Scan",
"project": "frontend",
"new_issue_count": 2,
"scan_url": "https://app.corgea.com/scans/def456"
}
]
}
}
```
外側のエンベロープ（`event_id`、`event_type`、`timestamp`、`data`）は[標準ペイロード構造](#payload-structure)に従います。`data`オブジェクトには次のフィールドが含まれます。
| フィールド | タイプ | 説明 |
| --------------------------------- | ---------- | -------------------------------------- |
| `title` | 文字列 | レポートの表示タイトル |
| `company` | 文字列 | 会社ID |
| `company_name` | 文字列 | 会社名 |
| `total_new_issues` | 整数 | ペイロード内の全スキャン実行における新規問題の合計 |
| `message` | 文字列 | 人間が読みやすい要約で、平文通知(例:Slack)に対応 |
| `scan_runs` | 配列 | 1件以上の新しい検出結果があったスキャン実行ごとのエントリ |
| `scan_runs[].scheduled_scan_name` | 文字列 | スケジュールスキャン構成の名前 |
| `scan_runs[].project` | 文字列 \|null | プロジェクト名、またはリンクされていない場合は `null` |
| `scan_runs[].new_issue_count` | 整数 | この実行で検出された新しい問題の件数 |
| `scan_runs[].scan_url` | 文字列 \|null | Corgeaのスキャン結果へのディープリンク。利用できない場合は`null` |
***
## よくある質問
はい!エンドポイントにはイベントを識別するための `X-Corgea-Event` ヘッダーと `event_type` フィールドが表示されます。
明確な制限はありませんが、目的ごとに整理することをおすすめします(例:チームやツールごとに1つ)。
Corgeaは指数関数的なバックオフで3回再試行します。10回連続で失敗すると、Webhookは自動的に一時停止します。
はい!「Test Webhook」ボタンを使って、実際のイベントを待たずにサンプルペイロードを送信できます。Slack Workflow Builderの場合、サンプルはフラットで、空でない `message` とトリアージキー(`pull_request_id`、 `scan_url`、 `true_positive_count`、 `company`)が含まれています。 `company_id` も従来のテストクライアント向けに(同じ値で)含まれています。
はい。**Scan Event Filters**で、**Only pull request / merge request scans**と**Only completed scans with true-positive findings**を有効にします。`scan.failed`と`scan.completed`を登録してください。検出結果のフィルターは`scan.failed`には適用されません。
はい!CorgeaはHMAC署名検証用のシークレットキーを自動的に生成します(`X-Corgea-Signature`)。宛先固有の認証トークン用のカスタムヘッダーも追加できます。
直接ではありませんが、プロジェクトごとに絞り込むことができます。また、エンドポイントで受信したペイロードをフィルタリングすることもできます。
ペイロードはHTTPS(TLS)経由で送信され、転送中の暗号化を提供します。認証にはHMAC署名を使用してください。
デリバリーログはコンプライアンスやデバッグのために保持されます。プランに具体的な保持期間を確認してください。
はい!webhookの配信履歴にアクセスし、失敗した配信があれば「再試行」をクリックしてください。
ファイアウォールでホワイトリストに登録すべき現在のIPアドレスリストについてはサポートに連絡してください。
***
**ご質問や問題がある場合** 連絡 [Corgeaサポート](mailto:support@corgea.com)