Getting Started

Quickstart

Get your first F1 live timing webhook delivery in under 5 minutes. No credit card required. The same webhook mechanism works for any sport RaceHooks supports as the platform expands — IndyCar and NASCAR feeds will use the identical integration pattern.

Prerequisites
  • A free RaceHooks account — sign up at racehooks.io/signup and verify your email (see the Authentication guide)
  • Your API credentials — client_id and client_secret from the console API Keys page
  • A publicly reachable HTTPS endpoint, or use the Simulate feature to test locally
  • curl, Node.js, or Python for the API calls below
1

Get your token

Exchange your API client credentials for a Bearer token — create them on the API Keys page. All API calls require the token in the Authorization header; tokens expire after 12 hours.

bash
curl -X POST https://api.racehooks.io/v1/oauth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "client_credentials"
  }'

# Response — the token is an opaque string (not a JWT); treat it as a secret
{
  "access_token": "vN3xKq81tYw2LmR9bC6dF7gHjS5aU0eIPo4Z",
  "token_type": "Bearer",
  "expires_in": 43200
}
✦
New here? First create your account and verify your email, then grab your credentials from the API Keys page — or fetch them programmatically with POST /v1/oauth/credentials.
2

Register your webhook

Register an endpoint URL and subscribe it to a feed. This example uses driver.list — a Free-tier feed carrying the session roster, so this call works on a Free account.

ℹ
Live timing feeds like timing.data (lap times, sector times, gaps, positions) require the Developer tier — subscribing to one on Free returns 402. You can still receive them for free by replaying a past session through your webhook with Simulate (Step 4).
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": "driver.list"
  }'

# Response
{
  "data": {
    "webhookId": "wh_7a3b9c2d",
    "webhookUrl": "https://your-app.com/f1",
    "feedId": "driver.list",
    "active": true,
    "webhookSecret": "whsec_..."   ← use to verify signatures
  }
}
✦
The webhookSecret is returned at creation and used to verify incoming signatures. If you lose it, retrieve it anytime with GET /v1/webhooks/:id/secret, or issue a new one with POST /v1/webhooks/:id/rotate-secret.
3

Handle incoming deliveries

RaceHooks POSTs a JSON payload to your endpoint for every matching event. Every delivery — on every tier, Free included — carries an X-RaceHooks-Signature header — an HMAC-SHA256 signature you can use to verify the payload originated from RaceHooks.

A typical driver.list payload looks like:

json
{
  "feed": "driver.list",
  "sessionId": "9560",
  "utc": "2026-06-08T14:32:18.441Z",
  "drivers": [
    {
      "driverId": "verstappen-max",
      "constructorId": "red-bull-racing",
      "number": "1",
      "tla": "VER",
      "name": "Max Verstappen",
      "team": "Red Bull Racing"
    },
    {
      "driverId": "norris-lando",
      "constructorId": "mclaren",
      "number": "4",
      "tla": "NOR",
      "name": "Lando Norris",
      "team": "McLaren F1 Team"
    },
    {
      "driverId": "leclerc-charles",
      "constructorId": "ferrari",
      "number": "16",
      "tla": "LEC",
      "name": "Charles Leclerc",
      "team": "Scuderia Ferrari"
    },
    {
      "driverId": "hamilton-lewis",
      "constructorId": "ferrari",
      "number": "44",
      "tla": "HAM",
      "name": "Lewis Hamilton",
      "team": "Scuderia Ferrari"
    },
    {
      "driverId": "russell-george",
      "constructorId": "mercedes",
      "number": "63",
      "tla": "RUS",
      "name": "George Russell",
      "team": "Mercedes-AMG Petronas F1 Team"
    }
  ]
}

To verify the signature:

webhook-handler.ts
// Node.js — verify an incoming RaceHooks delivery
import crypto from 'crypto';

function verifySignature(
  payload: string,        // req.body as raw string
  signature: string,      // X-RaceHooks-Signature header value
  secret: string          // your webhook secret
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}
4

Test with Simulate

You don't need to wait for a live race to test. Use Simulate to replay this season's F1 sessions against your registered webhooks at up to 10× speed (the full historical archive is on Custom).

bash
# 1. Prepare the artifact (main API, Bearer header)
curl -X POST https://api.racehooks.io/v1/simulate/prepare \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "2026-canada_r" }'

# 2. Play it into your webhooks at 10x — on the simulate host, token as a query param
curl "https://simulate.racehooks.io/v1/simulate/stream?session=2026-canada_r&speed=10&sinks=webhook&token=${TOKEN}"

# Deliveries arrive at your endpoint exactly as they would live.
# The demo session is pre-warmed; for other sessions, poll
# GET https://api.racehooks.io/v1/simulate/status?session=<id> until status is "ready".

Heads up on volume: a replay POSTs every recorded event to every active endpoint — tens of thousands of deliveries for a full race, compressed by the speed multiplier. Free capture bins (webhook.site and similar) rate-limit under that load; use speed=1 with a single endpoint for clean samples. The curated demo race additionally delivers the full Analytics feed set to all endpoints regardless of tier — it's the showcase. See delivery volume during replays.

You can also start a simulation from the Simulate page in the console — pick one of this season's races, set the speed, and watch deliveries arrive in your logs in real time.

What's next
Browse all 50+ feeds
See cadences, payload schemas, and tier availability
→
Enable analytics enrichment
Add tire state, win probability, and pit prediction to every payload
→
API reference
Full endpoint documentation with request/response schemas
→
Feed catalog →