API de alertas webhook

Pontos finais

Verifique cada alerta

Use o corpo bruto da requisição exatamente como recebido. O cabeçalho contém uma assinatura, ou duas durante uma rotação de segredo. Aceite a requisição quando qualquer assinatura corresponder.

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);
  });
}

Rotacione segredos com 24 horas de carência

A rotação retorna um novo segredo, uma única vez. Até o fim do período de carência, cada alerta é assinado primeiro com o segredo novo e depois com o anterior, então os receptores que ainda usam o segredo antigo continuam funcionando.

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

Códigos de status HTTP

Estes são os códigos de status HTTP que você deve tratar para distinguir respostas bem-sucedidas, problemas de autenticação, créditos, limites de taxa, dados ausentes e falhas de origem.