Webhook Alerts API

Endpoints

Verify every alert

Use the raw request body exactly as received. The header holds one signature, or two during a secret rotation. Accept the request when any signature matches.

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

Rotate secrets with a 24 hour grace period

Rotating returns a new secret once. Until the grace period ends, each alert is signed with the new secret first and the previous secret second, so receivers that still use the old secret keep working.

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

HTTP status codes

These are the HTTP status codes to handle, so you can tell apart successful responses, auth issues, credits, rate limits, missing data, and upstream failures.