웹훅 알림 API

엔드포인트

모든 알림 검증하기

받은 그대로의 원본 요청 본문을 사용하세요. 헤더에는 서명이 하나, 시크릿 교체 중에는 두 개 들어 있습니다. 서명 중 하나라도 일치하면 요청을 받아들이세요.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON parsing.
function verifyDomScanWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-domscan-timestamp'];
  const header = headers['x-domscan-signature'] || '';
  if (!/^\d{10}$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from('sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex'));
  // One entry normally; two during a secret rotation (new secret first).
  return header.split(',').some((entry) => {
    const candidate = Buffer.from(entry.trim());
    return candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected);
  });
}

24시간 유예 기간으로 시크릿 교체

교체하면 새 시크릿이 한 번만 반환됩니다. 유예 기간이 끝날 때까지 모든 알림은 새 시크릿, 이전 시크릿 순으로 서명되므로, 아직 이전 시크릿을 쓰는 수신 측도 계속 동작합니다.

X-DomScan-Signature: sha256=<new>,sha256=<previous>

HTTP 상태 코드

다음은 처리해야 할 HTTP 상태 코드입니다. 성공 응답, 인증 문제, 크레딧, 속도 제한, 누락된 데이터, 업스트림 장애를 구분하는 데 사용하세요.