API

Webhooks

Get a POST to your endpoint when a scan finishes or a monitored site's score changes.

Events

Event	Fires when
scan.completed	A scan reaches a final grade.
scan.failed	A scan can't complete (timeout, unreachable URL).
monitor.score_changed	A monitored site's overall score moves ±3 points.

Verifying signatures

Every payload is signed with HMAC-SHA256 using your webhook secret.

ts
import { createHmac, timingSafeEqual } from "crypto";

const expected = createHmac("sha256", process.env.MAGNETIC_WEBHOOK_SECRET!)
  .update(rawBody)
  .digest("hex");

if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return new Response("Invalid signature", { status: 401 });
}

Always verify before processing

Anyone who knows your endpoint URL can POST to it. Verify the signature first, then trust the payload.