Webhook
組織内で興味深いことが起こるたびにHMAC署名付きイベント配信を受信するアウトバウンドWebhookエンドポイントを登録します。管理者ページはエンドポイントCRUDを処理します。詳細な配信契約 — イベントカタログ、署名検証、再試行スケジュール — はAPI → Webhookにあります。
場所
サイドバー → 統合セクションの下のWebhook、/organization/webhooksにあります。
エンドポイントの作成
+ エンドポイントを追加をクリックします。ダイアログは以下を要求します:
- URL — 配信を受信する公開HTTPS URL。トンネル (cloudflared、ngrok) はローカル開発で問題なく動作します。
- 説明 (オプション) — 短いメモ、例: 「Slack #appsec notifier」または「Jira ticket creator」。
- イベント — サブスクライブするイベントタイプ。今日提供される4つのイベントは
assignment.created、assignment.completed、sarif.ingested、certificate.issuedです。
送信時、ダイアログは署名シークレット (whsec_…) を一度だけ表示します。すぐにシークレットマネージャーにコピーしてください。すべての受信配信を検証するために必要です。Node、Python、Goでの検証コードについてはAPI → Webhookを参照してください。
エンドポイントのリスト
リストビューには、組織のすべてのWebhookエンドポイントが表示されます。各行にはURL、サブスクライブされたイベント、作成者、ライブヘルスインジケーターが含まれます:
| ステータス | 意味 |
|---|---|
| 正常 | 最後の配信が2xxレスポンスを返しました。 |
| 失敗 | 最後の配信が非2xxレスポンスを返したかタイムアウトしましたが、エンドポイントはまだ再試行されています。 |
| 保留中 | エンドポイントは存在しますが、まだ最初の配信を受信していません。 |
| 無効 | エンドポイントは最近の配信で再試行スケジュールを使い果たし、自動的に無効化されました。最後の配信タイムスタンプは、いつ失敗したかを確認できるように保持されます。 |
編集と削除
編集をクリックして、URL、説明、またはイベントサブスクリプションリストを更新します。アクティブトグルをオフに切り替えると、エンドポイントを削除せずに配信が一時停止されます。オンに戻すと、配信が再開され、自動無効化状態がクリアされます。削除をクリックして、エンドポイントを完全に削除します — 保留中の配信はキャンセルされ、行はリストから削除されます。
最近の配信の検査
各行の⟳ 配信ボタンは、そのエンドポイントの最近50回の配信試行をリストするドロワーを開きます。各エントリには、イベントタイプ、イベントID、現在のステータス (pending / delivered / failed / exhausted)、試行回数、エンドポイントが返したHTTPステータスコード、エラーメッセージ、タイムスタンプが表示されます。
このビューを使用すると、自身のレシーバーを計装せずに動作が悪いコンシューマーをデバッグできます — レシーバーが5xxを返している場合、ここに表示されるメッセージはアプリケーションがログに記録したものと同じメッセージです。
再試行と自動無効化
失敗した配信は、合計最大5回の試行のために1m → 5m → 30m → 2hスケジュールで再試行されます。5回目の失敗後、エンドポイントは自動的に無効化され、最後の配信はexhaustedとマークされます。再有効化するには、レシーバーを修正してから、編集ダイアログでアクティブをクリックするか、{"isActive": true}を含むAPI PATCH /api/sch/org/webhooks/{id}を送信します。
プログラム的アクセス
このページのすべてのアクションは公開APIからも到達可能です — CRUDサーフェスと配信契約についてはAPI → Webhookを参照。