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.
1. What your endpoint must accept
Section titled “1. What your endpoint must accept”Each delivery is a single HTTP request:
| Aspect | Value |
|---|---|
| Method | POST |
| Body | JSON array of transformed messages (one batch can hold multiple items) |
| Timeout | 10 seconds from the sender's perspective |
| Success | Status 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).
Signature headers
Section titled “Signature headers”Every POST includes:
| Header | Meaning |
|---|---|
X-Signature-Expiration-Timestamp | Unix time; signatures older than about 5 minutes should be rejected on your side too |
X-Signature-SHA256 | HMAC-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 beforeJSON.parse. Do not re-serialize a parsed object - whitespace, key order, and number formatting must match what was signed.{expirationTimestamp}is the header value ofX-Signature-Expiration-Timestampas a decimal Unix timestamp in seconds (same characters as in the header, no extra padding).
Verify in this order:
- 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. - HMAC -
expected = HMAC-SHA256(secret, raw_body + "." + expiration_timestamp)as lowercase hex. Compare toX-Signature-SHA256with a constant-time equality check (for examplecrypto.timingSafeEqualin Node orhmac.compare_digestin Python). Do not use==on strings. - Parse JSON - only after steps 1-2 succeed.
- Idempotency - each object in the batch should carry a stable message identifier (commonly
idoruuidin 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_valueexpected_hex = HMAC-SHA256(secret, signing_input) # lowercase hexconstant_time_equal(expected_hex, X-Signature-SHA256)2. Related docs
Section titled “2. Related docs”| Goal | Page |
|---|---|
| Poll live scores over REST while you build | Build a livescore board |
| Diff-based REST sync vs live push | Incremental sync |