API d’alertes webhook

Points de terminaison

Vérifiez chaque alerte

Utilisez le corps brut de la requête exactement tel que reçu. L’en-tête contient une signature, ou deux pendant une rotation de secret. Acceptez la requête dès qu’une signature correspond.

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

Faites pivoter vos secrets avec 24 heures de période de grâce

La rotation renvoie un nouveau secret, une seule fois. Jusqu’à la fin de la période de grâce, chaque alerte est signée d’abord avec le nouveau secret, puis avec le précédent, afin que les récepteurs qui utilisent encore l’ancien secret continuent de fonctionner.

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

Codes de statut HTTP

Voici les codes d'état HTTP à gérer, afin de distinguer les réponses réussies, les problèmes d'authentification, les crédits, les limites de débit, les données introuvables et les erreurs en amont.