API för webhook-varningar

Slutpunkter

Verifiera varje varning

Använd begärans råa innehåll exakt som det togs emot. Headern innehåller en signatur, eller två under en hemlighetsrotation. Godkänn begäran när någon av signaturerna matchar.

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

Rotera hemligheter med 24 timmars övergångsperiod

Rotationen returnerar en ny hemlighet en gång. Tills övergångsperioden är slut signeras varje varning först med den nya hemligheten och sedan med den tidigare, så att mottagare som fortfarande använder den gamla hemligheten fortsätter fungera.

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

HTTP-statuskoder

Det här är de HTTP-statuskoder som du bör hantera, så att du kan skilja mellan lyckade svar, autentiseringsproblem, krediter, hastighetsgränser, saknade data och fel hos externa tjänster.