Webhook-Alarm-API

Endpunkte

Jeden Alarm prüfen

Verwenden Sie den Anfrage-Body genau so, wie er eingegangen ist. Der Header enthält eine Signatur, während einer Rotation des Geheimnisses zwei. Akzeptieren Sie die Anfrage, wenn eine der Signaturen passt.

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

Geheimnisse mit 24 Stunden Übergangsfrist rotieren

Beim Rotieren wird einmalig ein neues Geheimnis zurückgegeben. Bis die Übergangsfrist endet, wird jeder Alarm zuerst mit dem neuen und danach mit dem vorherigen Geheimnis signiert, sodass Empfänger, die noch das alte Geheimnis verwenden, weiter funktionieren.

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

HTTP-Statuscodes

Das sind die HTTP-Statuscodes, die Sie behandeln sollten, damit Sie erfolgreiche Antworten, Authentifizierungsprobleme, Credits, Ratenlimits, fehlende Daten und Upstream-Fehler unterscheiden können.