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-коды состояния, которые нужно обрабатывать, чтобы различать успешные ответы, проблемы аутентификации, кредиты, лимиты запросов, отсутствующие данные и ошибки вышестоящих сервисов.