Documentation / Guides

Webhooks

Push race status changes and result publication to your own HTTPS endpoint: events, the signed payload, retries and how to verify a delivery.

Webhooks push events to an HTTPS endpoint you control, so you don't have to poll. They carry the same events as the WebSocket stream — pick whichever suits you: a long-lived socket, or plain HTTP callbacks your server already knows how to accept. Live keys only; endpoints are registered on request today (send us your URL and the events/regions you want), with self-serve management coming to your dashboard.

Events

  • result.received — a race has completed and its result landed.
  • race.status_changed — a race moved to a new lifecycle status (carries status and previous_status).
  • card.updated — a new upcoming card, or a runner change on one.

Choose region GB, AU or both per endpoint.

The delivery

Each event is a single HTTPS POST with a JSON body and these headers:

Content-Type: application/json
X-GAPI-Event: race.status_changed
X-GAPI-Delivery: 84213
X-GAPI-Signature: sha256=9f2a…
{ "event": "race.status_changed", "channel": "status:AU",
  "race_id": 3661572768, "track": "Warragul",
  "status": "off", "previous_status": "scheduled",
  "scheduled_start": "2026-08-04T09:25:00Z", "ts": "2026-08-04T09:25:03Z" }

Verify every delivery

We sign the raw request body with your endpoint's secret using HMAC-SHA256. Recompute it and compare in constant time against X-GAPI-Signature before trusting a payload:

$secret   = "whsec_…";
$expected = "sha256=" . hash_hmac("sha256", file_get_contents("php://input"), $secret);
if (!hash_equals($expected, $_SERVER["HTTP_X_GAPI_SIGNATURE"] ?? "")) { http_response_code(401); exit; }

Retries & delivery guarantees

Respond 2xx to acknowledge. A 5xx, timeout or network error is retried with backoff (roughly 1m, 5m, 15m, 1h, 6h) for up to six attempts; a 4xx is treated as a permanent rejection and not retried, so keep your endpoint returning 2xx even when you choose to ignore an event. Delivery is at-least-once — the same event can arrive again on a retry, so dedupe on X-GAPI-Delivery, which is stable per delivery.

Result completeness

A result.received fires when a race first completes; because placings can arrive after the winner, read result_status on the race (see Data freshness) to tell a provisional result from a final one.