ドメイン監視のための Webhook アラート API

エンドポイント

すべてのアラートを検証

受信したままの生のリクエスト本文を使用してください。ヘッダーには署名が 1 つ入り、シークレットのローテーション中は 2 つ入ります。いずれかの署名が一致すれば、そのリクエストを受け入れます。

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ステータスコードを明記しています。