We call you when the score moves

1. 01

   Register

   In the dashboard's Webhooks tab, add the URL that should receive events. It must be https:// on a public host; plain HTTP and private addresses are refused.

2. 02

   Keep the secret

   Each endpoint gets its own signing secret, shown once when you create it or rotate it. Store it next to your API key.

3. 03

   Choose what to hear

   Pick event types and narrow by sport, league or fixture. Leave a filter empty and it lets everything through.

1. 1Read the raw bodyBefore any JSON middleware touches it. The HMAC covers the exact bytes we sent.
2. 2Split the headerSeparate t and v1 at the comma, then each name from its value at the first equals sign.
3. 3Check the timeReject the request if t is more than five minutes from now.
4. 4Recompute and compareHMAC-SHA256 over t, a full stop and the body, keyed with the signing secret; compare with v1 in constant time.

// webhook.ts: receive and verify events (Node 22+, no dependencies)
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = process.env.WEBHOOK_SIGNING_SECRET!; // shown once, when the endpoint is created
const TOLERANCE_S = 300;
const seen = new Set<string>(); // use Redis or your database in production

export function verify(header: string | undefined, raw: Buffer, secret: string): boolean {
  if (!header) return false;
  const parts = new Map(header.split(",").map((kv) => kv.split("=", 2) as [string, string]));
  const t = parts.get("t");
  const v1 = parts.get("v1");
  if (!t || !v1) return false;

  const age = Date.now() / 1000 - Number(t);
  if (!Number.isFinite(age) || Math.abs(age) > TOLERANCE_S) return false; // stale or replayed

  const expected = createHmac("sha256", secret).update(`${t}.`).update(raw).digest();
  const given = Buffer.from(v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (c: Buffer) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks); // the exact bytes: verify before parsing
    if (!verify(req.headers["dsa-signature"] as string | undefined, raw, SECRET)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(204).end(); // answer inside 10 seconds, then do the work

    const event = JSON.parse(raw.toString("utf8"));
    if (seen.has(event.id)) return; // a retry of something already handled
    seen.add(event.id);
    enqueue(event);
  });
}).listen(3000);

function enqueue(event: { id: string; type: string; createdAt: string; data: Record<string, unknown> }) {
  // Hand off to your job queue. data.changes is a partial Fixture:
  // deep-merge it exactly like a WebSocket delta.
}

Counts as success

2xx within 10 s

Any status from 200 to 299 will do; 204 No Content is the tidiest.

Counts as failure

anything else

4xx, 5xx, a timeout, a connection error and redirects too: we do not follow a 3xx, so point the endpoint at the final URL.

Retry schedule

10 s · 1 min · 5 min · 30 min · 2 h · 6 h

Each wait follows the previous failed attempt. After the sixth retry the delivery is marked failed.

Disabled endpoints

24 h of failures

If every attempt to an endpoint fails for a whole day, we stop sending to it. Fix it, then re-enable it in the dashboard.

• Verify on raw bytesCompute the HMAC over the body exactly as it arrived. Parsing and re-serialising JSON changes the bytes.
• Compare in constant timetimingSafeEqual in Node, hmac.compare_digest in Python. A plain == leaks how much of a guess was right.
• Reject old timestampsFive minutes either way is a sensible window. Keep your server clock synced with NTP.
• Acknowledge firstReturn 2xx as soon as the signature checks out; do the slow work from a queue.
• Deduplicate by event idRemember ids for longer than the retry window, a day or more, so a late retry is recognised.
• Never trust arrival orderCompare createdAt before applying a change, or re-read the fixture over REST when order matters.
• Guard the secretStore the signing secret like an API key. If it may have leaked, rotate it in the dashboard; the new one is shown once.
• Watch for failuresAfter 24 hours in which every attempt failed, the endpoint is disabled. Turn it back on in the dashboard once it is fixed.

Testing locally? Endpoints must be public HTTPS, so expose your machine through a tunnel and use the dashboard's test delivery, which sends a ping event.