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 → 편집에서 확인하거나 재생성할 수 있습니다.