Webhookmeldingen-API

Endpoints

Verifieer elke melding

Gebruik de ruwe body van het verzoek precies zoals ontvangen. De header bevat één handtekening, of twee tijdens een geheimrotatie. Accepteer het verzoek zodra een van de handtekeningen overeenkomt.

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

Roteer geheimen met een respijtperiode van 24 uur

Bij het roteren wordt het nieuwe geheim één keer teruggegeven. Totdat de respijtperiode afloopt, wordt elke melding eerst met het nieuwe geheim en daarna met het vorige geheim ondertekend, zodat ontvangers die nog het oude geheim gebruiken blijven werken.

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

HTTP-statuscodes

Dit zijn de HTTP-statuscodes die je moet afhandelen, zodat je succesvolle responses, authenticatieproblemen, credits, ratelimieten, ontbrekende gegevens en upstreamfouten kunt onderscheiden.