Webhooks

A webhook is a registered endpoint URL with one or more feed subscriptions. RaceHooks POSTs a JSON payload to that URL for every matching event during a live session. The webhook infrastructure is sport-agnostic: the same endpoint, signature verification, and filter system works across every sport RaceHooks supports. One endpoint can subscribe to many feeds (all sharing a single signing secret), each subscription can carry its own filters to narrow which events trigger a delivery, and the X-RaceHooks-Feed header tells you which feed produced each payload.

# Subscribe one endpoint to several feeds (all share one signing secret).
# Use "feedId" for a single feed, or "subscriptions" for per-feed filters.
curl -X POST https://api.racehooks.io/v1/webhooks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/f1",
    "feedIds": ["timing.data", "session.status"]
  }'

# Response (feedIds / subscriptions form) — one endpoint carrying its per-feed
# subscriptions. The id is at data.webhookId.
{
  "data": {
    "webhookId": "V1StGXR8_Z5jdHi6B-myT",
    "webhookUrl": "https://your-app.com/f1",
    "webhookMethod": "post",
    "subscriptions": [
      { "feedId": "session.status", "seriesId": "f1", "filters": {}, "active": true, ... },
      { "feedId": "timing.data",    "seriesId": "f1", "filters": {}, "active": true, ... }
    ],
    "webhookSecret": "3f8a9c1d5e7b2a4f6c8e0d1b3a5f7c9e2d4b6a8f0c1e3d5b7a9f2c4e6d8b0a1c",
    "tier": "developer"
  }
}
# webhookSecret is also retrievable anytime via GET /v1/webhooks/:id/secret.

# The single-feedId form returns a different shape — the id is at
# data.webhook.webhookId:
# { "data": { "webhook": { "webhookId": "...", "feedId": "...", ... },
#             "webhookSecret": "...", "tier": "..." } }

# Filter by driver TLA codes
curl -X POST https://api.racehooks.io/v1/webhooks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/verstappen",
    "feedId": "timing.data",
    "filters": {
      "drivers": ["VER", "NOR"]
    }
  }'

# Filter by constructor keyword + position range
curl -X POST https://api.racehooks.io/v1/webhooks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/ferrari-top5",
    "feedId": "timing.data",
    "filters": {
      "constructors": ["ferrari"],
      "positions": { "min": 1, "max": 5 }
    }
  }'

X-RaceHooks-Signature-V1  t=<sentAtMs>,v1=HMAC-SHA256(webhookSecret, "<sentAtMs>." + rawRequestBody)
X-RaceHooks-Signature     sha256=HMAC-SHA256(webhookSecret, rawRequestBody)

import crypto from "crypto";
import express from "express";

const app = express();
const TOLERANCE_SECONDS = 300;

// Verify X-RaceHooks-Signature-V1: "t=<sentAtMs>,v1=<hex>", where
// hex = HMAC-SHA256(secret, `${t}.${rawBody}`). t is signed, so the age
// check below is real replay protection.
function verifyV1(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=", 2)));
  const t = parts.t, sig = parts.v1;
  if (!t || !/^\d+$/.test(t) || !sig) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
  if (sig.length !== expected.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return false;
  return Math.abs(Date.now() - Number(t)) <= TOLERANCE_SECONDS * 1000;
}

// Raw body middleware — verify the exact bytes, not re-serialized JSON
app.post("/f1-hook", express.raw({ type: "application/json" }), (req, res) => {
  const v1 = req.headers["x-racehooks-signature-v1"] as string | undefined;
  if (!v1 || !verifyV1(req.body, v1, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid or stale signature");
  }
  // Dedupe: X-RaceHooks-Delivery-Id is stable across the automatic retries.
  const payload = JSON.parse(req.body.toString());
  // handle payload...
  res.sendStatus(200);
});

// Legacy body-only check (still sent, still valid — proves origin, not freshness):
//   "sha256=" + HMAC-SHA256(secret, rawBody) === req.headers["x-racehooks-signature"]
// racehooks <= 0.4.0's verifySignatureBoolean(req.body, sig, secret) checks this one.

POST /f1 HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-RaceHooks-Feed: events.race
X-RaceHooks-Series: f1
X-RaceHooks-Mode: replay
X-RaceHooks-Replay-Session: 2026-canada_r
X-RaceHooks-Replay-Speed: 10
X-RaceHooks-Replay-Run-Id: <run id>
X-RaceHooks-Webhook-Id: <your webhook id>
X-RaceHooks-Delivery-Id: <uuid>
X-RaceHooks-Sent-At: <epoch ms>
X-RaceHooks-Signature-V1: t=<epoch ms>,v1=<hex>
X-RaceHooks-Signature: sha256=<hex>

{
  "feed": "events.race",
  "sessionId": "2026-canada_r",
  "event": "lead.change",
  "lap": 30,
  "utc": "2026-10-05T18:49:20.412Z",
  "data": {
    "newLeader": {
      "driverId": "antonelli-kimi",
      "constructorId": "mercedes",
      "number": "12",
      "tla": "ANT",
      "name": "Kimi Antonelli",
      "team": "Mercedes"
    },
    "previousLeader": {
      "driverId": "russell-george",
      "constructorId": "mercedes",
      "number": "63",
      "tla": "RUS",
      "name": "George Russell",
      "team": "Mercedes"
    },
    "viaOvertake": true
  }
}

import crypto from "crypto";
import express from "express";

const app = express();
const TOLERANCE_MS = 300_000;
const seen = new Set<string>(); // use a shared store with a TTL in production

// X-RaceHooks-Signature-V1 is "t=<sentAtMs>,v1=<hex>", where hex = HMAC-SHA256(secret, "<t>.<raw body>").
function verifyV1(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=", 2)));
  const t = parts.t, sig = parts.v1;
  if (!t || !/^\d+$/.test(t) || !sig) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false; // constant-time compare
  return Math.abs(Date.now() - Number(t)) <= TOLERANCE_MS;
}

app.post("/f1", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the signature against the raw bytes before parsing anything.
  const sig = req.header("X-RaceHooks-Signature-V1");
  if (!sig || !verifyV1(req.body, sig, process.env.WEBHOOK_SECRET!)) return res.sendStatus(401);

  // 2. Dedupe on the delivery id: deliveries are at-least-once, and the id is the same across retries.
  const deliveryId = req.header("X-RaceHooks-Delivery-Id")!;
  if (seen.has(deliveryId)) return res.sendStatus(200);
  seen.add(deliveryId);

  const body = JSON.parse(req.body.toString());

  // 3. Replay deliveries are your test path: handle them, but keep them out of production state.
  const isReplay = req.header("X-RaceHooks-Mode") === "replay";

  if (body.feed === "events.race" && body.event === "lead.change") {
    console.log(`${isReplay ? "[replay] " : ""}lap ${body.lap}: ${body.data.newLeader.tla} takes the lead from ${body.data.previousLeader.tla}`);
    // [replay] lap 30: ANT takes the lead from RUS
  }
  res.sendStatus(200); // any 2xx within 10 seconds is a success
});

curl -X POST https://api.racehooks.io/v1/webhooks/V1StGXR8_Z5jdHi6B-myT/rotate-secret \
  -H "Authorization: Bearer ${TOKEN}"

# Response — new secret (also retrievable via GET /v1/webhooks/:id/secret)
{
  "data": {
    "webhookId": "V1StGXR8_Z5jdHi6B-myT",
    "webhookSecret": "a7c2e9f4b1d6083e5c7a9b2d4f6e8a0c1b3d5f7e9a2c4b6d8f0e1a3c5b7d9f2e",
    "note": "New secret is active for every feed on this endpoint."
  }
}

curl -X POST https://api.racehooks.io/v1/webhooks/V1StGXR8_Z5jdHi6B-myT/test \
  -H "Authorization: Bearer ${TOKEN}"

# Body your endpoint receives (headers include X-RaceHooks-Mode: test).
# "feed" (and the legacy "type") is the webhook's own feedId, matching the
# X-RaceHooks-Feed header — detect a ping by X-RaceHooks-Mode: test or data._test.
{
  "feed": "driver.list",
  "type": "driver.list",
  "sessionId": "test",
  "utc": "2026-10-02T12:00:00.000Z",
  "data": { "_test": true, "feedId": "driver.list", "timestamp": "2026-10-02T12:00:00.000Z" }
}

# API response
{ "data": { "delivered": true, "statusCode": 200, "errorMessage": null } }