API de alertas webhook

Endpoints

Verifica cada alerta

Usa el cuerpo de la solicitud sin procesar, exactamente como lo recibes. El encabezado contiene una firma, o dos durante una rotación de secreto. Acepta la solicitud cuando cualquiera de las firmas coincida.

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

Rota secretos con 24 horas de margen

Al rotar se devuelve un nuevo secreto, una sola vez. Hasta que termine el periodo de gracia, cada alerta se firma primero con el secreto nuevo y después con el anterior, así que los receptores que aún usan el secreto antiguo siguen funcionando.

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

Códigos de estado HTTP

Documentamos los códigos de estado HTTP que debes gestionar para distinguir respuestas correctas, problemas de autenticación o créditos, límites de frecuencia, datos inexistentes y fallos del servicio de origen.