Skip to content

Webhooks

For production live data, polling GET /v2/livescore in a loop is the wrong default once your contract includes push. Webhooks deliver batched JSON to a URL you register: events and incidents for competitions you are entitled to, in a shape meant for client integrations (not the raw internal feed).

The sections below are the delivery contract your handler must implement.

Each delivery is a single HTTP request:

AspectValue
MethodPOST
BodyJSON array of transformed messages (one batch can hold multiple items)
Timeout10 seconds from the sender's perspective
SuccessStatus 200 and response body exactly Accepted (plain text, case-sensitive)

Anything else is treated as a failed delivery (retries and monitoring are on the STATSCORE side - implement the success contract first).

Every POST includes:

HeaderMeaning
X-Signature-Expiration-TimestampUnix time; signatures older than about 5 minutes should be rejected on your side too
X-Signature-SHA256HMAC-SHA256 hex digest of the signing string below

The signed string is {payload}.{expirationTimestamp} where:

  • {payload} is the exact raw request body as UTF-8 bytes on the wire (the JSON array string). Read it from the socket before JSON.parse. Do not re-serialize a parsed object - whitespace, key order, and number formatting must match what was signed.
  • {expirationTimestamp} is the header value of X-Signature-Expiration-Timestamp as a decimal Unix timestamp in seconds (same characters as in the header, no extra padding).

Verify in this order:

  1. Expiration - reject if the header is missing, not a positive integer, or now > expiration (allow a small clock skew if you need it). Signature expiry is about 5 minutes; older deliveries must not be accepted even when the HMAC is valid.
  2. HMAC - expected = HMAC-SHA256(secret, raw_body + "." + expiration_timestamp) as lowercase hex. Compare to X-Signature-SHA256 with a constant-time equality check (for example crypto.timingSafeEqual in Node or hmac.compare_digest in Python). Do not use == on strings.
  3. Parse JSON - only after steps 1-2 succeed.
  4. Idempotency - each object in the batch should carry a stable message identifier (commonly id or uuid in the payload). Persist processed identifiers and make handlers idempotent: replays inside the expiry window are possible, and expiry alone is not replay protection. Apply side effects at most once per identifier across the whole batch.
signing_input = raw_utf8_body + "." + expiration_header_value
expected_hex = HMAC-SHA256(secret, signing_input) # lowercase hex
constant_time_equal(expected_hex, X-Signature-SHA256)
GoalPage
Poll live scores over REST while you buildBuild a livescore board
Diff-based REST sync vs live pushIncremental sync