Webhooks

Lifecycle

Webhooks have three operational states:

Create a webhook

Each webhook subscribes to exactly one feed. To receive multiple feeds at the same endpoint, create one webhook per feed. The webhookSecret is available at creation time and retrievable anytime via GET /v1/webhooks/:id/secret.

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": "timing.data"
  }'

# Response
{
  "data": {
    "webhookId": "wh_7a3b9c2d",
    "webhookUrl": "https://your-app.com/f1",
    "feedId": "timing.data",
    "active": true,
    "webhookSecret": "whsec_a3f9b..."  // retrievable anytime via GET /v1/webhooks/:id/secret
  }
}

Request fields

Filters

Filters let you narrow which events trigger a delivery. They are evaluated per payload before each delivery attempt — only matching events are sent. Filters are supported on per-driver feeds (timing.data, tire.stints, timing.driver-info, etc.) and on the events.race feed. Filters are validated strictly: an unrecognized key (e.g. a typo like driverNumber) or a wrong value type is rejected with a 400 invalid_filters error naming every violation, rather than silently delivering unfiltered.

Available filters

# 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 }
    }
  }'

HMAC signatures

Every delivery, on every tier — Free included — includes an X-RaceHooks-Signature header containing an HMAC-SHA256 signature of the request body. Verifying this header proves the delivery originated from RaceHooks and the body was not tampered with in transit.

The signature is computed as:

HMAC-SHA256(webhookSecret, rawRequestBody)

Always verify against the raw request body bytes, not the parsed JSON object. Use a timing-safe comparison function (timingSafeEqual in Node.js, hmac.compare_digest in Python, subtle.ConstantTimeCompare in Go) to prevent timing attacks.

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

Rotate a secret

If a secret is compromised or you want to rotate it for security hygiene, call the rotation endpoint. The new secret takes effect immediately.

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

# Response — new secret (also retrievable via GET /v1/webhooks/:id/secret)
{
  "data": {
    "webhookSecret": "whsec_b4c8d..."
  }
}

Live, replay, and test deliveries

Every delivery carries an X-RaceHooks-Mode header so you can tell real session data apart from a replay or a test. It has three values:

• live — real session data from a live session.
• replay — a Simulate replay of a past session (you started it from the Simulate page). Carries X-RaceHooks-Replay-Session (the original session id), X-RaceHooks-Replay-Run-Id (one id shared by every event of that replay run), and X-RaceHooks-Replay-Speed.
• test — a manual connectivity ping from the “Send test payload” button.

Delivery SLA and retries

RaceHooks retries failed deliveries with exponential backoff:

A delivery is considered successful when your endpoint returns a 2xx status code within 10 seconds. Any other response (timeout, 4xx, 5xx) triggers a retry.

Free and Developer are best-effort — there's no contractual delivery SLA. Custom includes a 99.5% delivery SLA, measured per calendar month, covering delivery infrastructure and excluding upstream feed availability; remedies are service credits, with full terms negotiated per contract.