API di avvisi webhook

Endpoint

Verifica ogni avviso

Usa il corpo grezzo della richiesta esattamente come ricevuto. L'intestazione contiene una firma, oppure due durante la rotazione di un segreto. Accetta la richiesta quando una qualsiasi firma corrisponde.

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

Ruota i segreti con 24 ore di tolleranza

La rotazione restituisce un nuovo segreto, una sola volta. Fino alla fine del periodo di tolleranza, ogni avviso è firmato prima con il nuovo segreto e poi con quello precedente, così i ricevitori che usano ancora il vecchio segreto continuano a funzionare.

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

Codici di stato HTTP

Questi sono i codici di stato HTTP da gestire, per distinguere risposte riuscite, problemi di autenticazione, crediti, limiti di frequenza, dati mancanti ed errori a monte.