Webhook이 도착하지 않는 경우
Webhook 채널로 알림 규칙을 만들었는데 서버에 아무것도 도착하지 않습니다. SilentShield가 언제 Webhook을 보내는지, 그리고 도중에 무엇이 이를 막을 수 있는지 설명합니다.
SilentShield가 Webhook을 보내는 시점
Webhook은 채널이 Webhook인 API 키의 알림 규칙만 보냅니다. SilentShield는 1분에 한 번 모든 활성 규칙을 확인합니다. 규칙의 조건이 시간 범위 안에서 충족되면 ‘알림 설정’ 페이지에 저장된 Webhook URL로 POST 요청을 한 번 보냅니다.
원인
규칙이 한 번도 발생하지 않았습니다
키의 ‘알림 규칙’ 페이지에서 ‘마지막 발생’ 열은 규칙이 마지막으로 발생한 시점을 보여 줍니다. ‘없음’(으)로 표시되면 조건이 아직 충족되지 않았고 아무것도 전송되지 않았습니다. 임곗값과 연산자를 분석의 수치와 비교해 보세요.
규칙이 시간 범위가 지나기를 기다리고 있습니다
규칙은 시간 범위(5m, 15m, 1h, 24h)마다 최대 한 번 발생합니다. 발생한 뒤에는 그 시간 범위가 지나야 다시 확인됩니다. 24h 규칙은 하루에 최대 한 번만 보냅니다.
Webhook URL이 저장되어 있지 않습니다
규칙은 채널만 선택하고, 주소 자체는 ‘알림 설정’ 페이지에서 저장합니다. 주소가 없으면 규칙은 발생하지만 아무것도 전송되지 않습니다. 주소는 Webhook 연동이 포함된 요금제에서만 저장할 수 있습니다.
인터넷에서 주소에 접근할 수 없습니다
SilentShield는 공개 주소로만 전송합니다. localhost, 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12 같은 로컬 및 내부 대상은 저장할 때와 연결할 때 다시 거부되며, 리디렉션 후에도 마찬가지입니다. 로컬 테스트에는 공개 HTTPS 주소가 있는 터널을 사용하세요.
서버 응답이 너무 느립니다
각 시도는 전체 응답을 최대 5초 동안 기다립니다. 즉시 2xx 상태로 응답하고 메시지는 그 후에 큐 등에서 처리하세요.
서버가 오류 또는 리디렉션으로 응답합니다
상태 코드 200~299만 전송 완료로 간주됩니다. 5xx, 408, 429 응답 후나 연결에 실패하면 SilentShield는 2초 후와 8초 후에 다시 시도하고 그다음에는 포기합니다. 401, 403, 404 같은 다른 4xx 코드는 다시 시도하지 않습니다. 엔드포인트 앞의 방화벽이나 봇 차단 기능은 흔히 403으로 응답합니다. 301, 302, 303 리디렉션 후에는 요청이 본문 없는 GET으로 이어지므로 최종 주소를 입력하세요.
서버에서 서명 확인이 실패합니다
시크릿을 저장했다면 모든 요청에 X-Signature-256 헤더가 붙습니다. 값은 sha256= 뒤에 본문의 HMAC-SHA256을 16진수로 붙인 것입니다. JSON을 파싱하기 전에 도착한 그대로의 원본 본문으로 계산하세요. 파싱한 뒤 다시 직렬화한 본문은 서명이 달라집니다. 시크릿이 없으면 이 헤더도 없습니다.
서버에 도착하는 내용
전송은 다음과 같습니다. X-Event-ID는 한 전송의 모든 시도에서 같습니다. 중복을 알아보는 데 사용하세요.
POST /your-webhook HTTP/1.1
Content-Type: application/json
X-Event-ID: 8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d
X-Signature-256: sha256=<hex>
{
"event_id": "8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d",
"alert_rule_id": "2a7c9e1b-3d4f-4b6a-8c0e-1f2a3b4c5d6e",
"alert_name": "bot-rate",
"api_key_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
"metric": "bot_rate",
"operator": "gt",
"threshold": 0.3,
"value": 0.42,
"fired_at": "2026-11-16T10:30:00Z"
}서명 확인
Node.js 예시입니다. rawBody는 변경하지 않은 요청 본문입니다.
const crypto = require("crypto");
function isValidSignature(rawBody, header, secret) {
const expected = "sha256=" +
crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const received = header || "";
return received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
// header = req.get("X-Signature-256")규칙과 채널을 설정하는 방법: 알림 규칙