面向域名监控与品牌保护的 Webhook 提醒 API 接口

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 状态码，帮助你区分成功响应、认证问题、额度不足、速率限制、数据不存在以及上游故障。