Webhook API reference

This page is for whoever sets up the sending side: a scoreboard OCR app, a scoring program or a script you wrote. It lists exactly what ScoreCastr Server expects and what it sends back. To turn the webhook on and get your URL, see Send live data by webhook first.

The request

Copy the URL from the Webhook URL box rather than building it by hand. The token is 32 characters and changes when you click Regenerate Token or turn ScoreCastr Server off and on again.

Send requests from an app, a server or a script. A web page on another website can't call the webhook from the visitor's browser, because ScoreCastr doesn't allow browser requests from other websites.

The body

A flat JSON object with one key per value. Send only what you have; a field you leave out keeps its current value on the match.

{
  "away_score": 14,
  "home_score": 21,
  "period": 3,
  "clock": "8:42"
}

• Home and away: away_ is the match's first team (the visitors), home_ the second.
• Numbers: send numbers (21) or numbers as text ("21"). Text that isn't a number is ignored for most number fields.
• Clocks: "MM:SS" (like "8:42") or a number of seconds.
• Yes or no fields: send true or false.
• Nesting: don't nest objects. Every field sits at the top level of the body.

Field names and aliases

Each sport has its own list, in the field guides: football, basketball, soccer, baseball and softball, volleyball, tennis and pickleball and ice hockey.

The general rules:

• snake_case or camelCase. Most fields take both: home_score or homeScore, time_remaining or timeRemaining.
• Common aliases. Scores also take home_points/away_points in football, home_runs/away_runs in baseball and softball, and home_goals/away_goals in ice hockey and field hockey. The clock also takes time_remaining and game_clock in several sports.
• Volleyball scores are sets won. home_score and away_score set sets won. The current set's points use home_current_set_points and away_current_set_points.
• Use the listed names. Names aren't checked against a fixed list, so an unexpected name can fail the update or save something you didn't intend. Stick to the names in the field guides.

A successful reply

A good update returns HTTP 200 with:

{
  "success": true,
  "fieldsUpdated": 2,
  "updateCount": 37,
  "changed": true
}

• fieldsUpdated: how many values or stat groups ScoreCastr wrote from this update.
• updateCount: how many updates this match has received since ScoreCastr Server was turned on.
• changed: true if the score, period or a stat actually changed. false means the values matched what the match already had, or nothing was recognized.

The update reaches the dashboard and the overlay straight away. The match's update count and last update time are saved with it.

Errors

Error replies are JSON with an error field (or message for invalid JSON).

Wrong content type

If the Content-Type header isn't application/json, ScoreCastr doesn't read the body. The request can still return 200, but nothing changes and changed is false. In basketball, it also sets both scores to 0.

Limits

• No rate limit is enforced. Each update is saved and sent to every open dashboard and overlay, so send when a value changes rather than on a fast timer.
• One match per URL. Each match has its own URL and token.
• Automatic shut-off. A feed that goes 12 hours without an update is turned off on its own, and its URL stops working.
• One connection type. A match uses the webhook or the XML File Monitor, not both. Setting up XML replaces the webhook and its URL.

Checklist

• POST to the full Webhook URL, copied from the Data Hub
• Content-Type: application/json on every request
• Flat JSON body with names from the sport's field guide
• Both scores in every basketball update
• Replies checked for "success": true while testing
• New URL used after Regenerate Token or a re-enable