Webhooks

A webhook is a registered endpoint URL paired with a feed subscription. 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. Each webhook is scoped to a single feed, and you can apply filters to narrow which events trigger a delivery.

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",
    "feedId": "timingdata"
  }'

# Response
{
  "data": {
    "webhookId": "wh_7a3b9c2d",
    "webhookUrl": "https://your-app.com/f1",
    "feedId": "timingdata",
    "active": true,
    "webhookSecret": "whsec_a3f9b..."  // shown once — store securely
  }
}

# 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": "timingdata",
    "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": "timingdata",
    "filters": {
      "constructors": ["ferrari"],
      "positions": { "min": 1, "max": 5 }
    }
  }'

HMAC-SHA256(webhookSecret, rawRequestBody)

import crypto from "crypto";
import { verifySignature } from "racehooks"; // or implement manually

// Express example — use raw body middleware
app.use("/f1-hook", express.raw({ type: "application/json" }));

app.post("/f1-hook", (req, res) => {
  const sig = req.headers["x-racehooks-signature"] as string;
  const ok  = verifySignature(req.body, sig, process.env.WEBHOOK_SECRET!);

  if (!ok) return res.status(401).send("Invalid signature");

  const payload = JSON.parse(req.body.toString());
  // handle payload...
  res.sendStatus(200);
});

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

# Response — new secret shown once
{
  "data": {
    "webhookSecret": "whsec_b4c8d..."
  }
}