Webhookフォーマット

SilentShieldはWebhookを通じてサーバーにリアルタイム通知を送信できます。ダッシュボード → 通知からWebhook URLを設定してください。

ペイロード構造

すべてのWebhookペイロードは以下の構造に従います：

{"event": "bot_detected", "timestamp": "2025-01-15T10:30:00Z", "data": {"keyId": "key_abc", "domain": "example.com", "ip": "203.0.113.42", "verdict": "bot", "score": 0.15, "userAgent": "Mozilla/5.0...", "page": "/contact"}}

イベントタイプ

Event	Description
`bot_detected`	リクエストがボットとして分類されたときにトリガーされます。
`bot_spike`	設定されたウィンドウ内でボット検出数がアラートしきい値を超えたときにトリガーされます。
`quota_warning`	クォータ使用量が80%または90%に達したときにトリガーされます。
`quota_exceeded`	月間クォータを超過したときにトリガーされます。
`domain_verification_failed`	ドメインの再検証チェックが失敗したときにトリガーされます。
`key_rotated`	APIキーがローテーションされたときにトリガーされます。

署名の検証

すべてのWebhookにはHMAC-SHA256署名を含むX-SilentShield-Signatureヘッダーが含まれます。Webhookが正当であることを確認するために、この署名を検証してください。

生のリクエストボディを取得します（パース前の文字列として）
X-SilentShield-Signatureヘッダーの値を取得します
Webhookシークレットをキーとして使用し、ボディのHMAC-SHA256を計算します
計算された署名とヘッダーの値を比較します

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

リトライポリシー

エンドポイントが2xx以外のステータスコードを返すか、タイムアウト（10秒）した場合、SilentShieldは指数バックオフ（1分、5分、30分）で最大3回配信を再試行します。3回の試行がすべて失敗した場合、Webhookは失敗としてマークされ、ダッシュボード → 通知 → 失敗した配信で確認できます。

Webhookシークレット

Webhookシークレットは、ダッシュボードでWebhookエンドポイントを作成する際に生成されます。ダッシュボード → 通知 → Webhook → 編集から確認または再生成できます。