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
A publicly reachable HTTPS endpoint, or use the Simulate feature to test locally
curl, Node.js, or Python for the API calls below

Get your token

Authenticate with your email and password to receive a Bearer token. All API calls require this token in the Authorization header.

bash

curl -X POST https://api.racehooks.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

# Response
{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": "2026-06-03T14:00:00Z"
  }
}

✦

You can also copy your token directly from the API Keys page in the console — no curl needed.

Register your webhook

Register an endpoint URL and subscribe it to a feed. This example uses timingdata — the most commonly used feed, delivering lap times, sector times, gaps, and positions on every lap completion.

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_..."   ← save this, shown once
  }
}

⚠

The webhookSecret is shown exactly once at creation time. Store it securely — you will need it to verify incoming signatures. If you lose it, rotate it from the webhook detail page.

Handle incoming deliveries

RaceHooks POSTs a JSON payload to your endpoint for every matching event. On the Starter tier and above, every delivery includes an X-RaceHooks-Signature header — an HMAC-SHA256 signature you can use to verify the payload originated from RaceHooks.

A typical timingdata payload looks like:

json

{
  "feed": "timingdata",
  "session": "2026 British Grand Prix — Race",
  "lap": 42,
  "data": {
    "1": {
      "position": 1,
      "gap": "—",
      "lastLap": "1:29.104",
      "s1": "28.441",
      "s2": "31.204",
      "s3": "29.459",
      "compound": "MEDIUM",
      "tireAge": 22
    },
    "4": {
      "position": 2,
      "gap": "+4.821",
      "lastLap": "1:29.381",
      "compound": "HARD",
      "tireAge": 8
    }
  }
}

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

Test with Simulate

You don't need to wait for a live race to test. Use Simulate to replay any historical F1 session against your registered webhooks at up to 10× speed.

bash

curl -X POST https://api.racehooks.io/v1/simulate \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "2024-british-r1",
    "speed": "10x"
  }'

# Response — poll GET /v1/simulate/:id until status = "completed"
{
  "data": {
    "simulationId": "sim_9f2c...",
    "status": "running",
    "sessionName": "2024 British Grand Prix — Race"
  }
}

You can also start a simulation from the Simulate page in the console — pick any race back to 2018, set the speed, and watch deliveries arrive in your logs in real time.

What's next

Browse all 23 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 →