When a scoreboard reader or another program sends football data to ScoreCastr, it has to use names ScoreCastr knows. This page lists every football field the webhook reads, the formats it accepts and what each one changes. Use it to set up the output fields in Scoreboard OCR or to write your own sender.
Before you start
- The Pro plan. The ScoreCastr button on the football Scoring tab opens the Data Hub.
- A webhook turned on for the match: on the Scoreboard OCR tab, pick HTTP Client (Webhooks) and click Enable ScoreCastr. Copy the Webhook URL. See Send live data by webhook.
- Scoreboard OCR users: set up the output in Connect Scoreboard OCR. The request format and replies are in the Webhook API reference.
Away means the away team you set when you created the match; home is the home team. Field names are case sensitive. Where two names are listed, either works.
Score, clock and game state
| Field names | What it changes | Format |
|---|---|---|
away_score, awayScore, away_points, awayPoints |
Away score | Number |
home_score, homeScore, home_points, homePoints |
Home score | Number |
quarter, currentQuarter, period |
Quarter | 1 to 4, 5 for overtime (shown as 1OT), 6 for 2OT. Also Q1, 1st, first, OT |
clock, time_remaining, timeRemaining |
Game clock | MM:SS, like 8:42, or a number of seconds |
down |
Down | 1 to 4, or 1st, 2nd, third and so on |
distance, yards_to_go, yardsToGo |
Yards to go | A number, or GOAL (G works too) |
ball_on, ballOn |
Ball on (yard line) | A number from 0 to 100, or text with a number in it |
possession |
Which team has the ball | away or home, lowercase |
away_timeouts, awayTimeouts |
Away timeouts left | Number |
home_timeouts, homeTimeouts |
Home timeouts left | Number |
You can send only the fields that changed. A field you leave out keeps its current value.
Team stats
Each stat has an away and a home version. Replace away_ with home_ for the home team.
| Field name (away) | Stat |
|---|---|
away_first_downs |
First downs |
away_total_yards |
Total yards |
away_passing_yards |
Passing yards |
away_rushing_yards |
Rushing yards |
away_penalties, away_penalty_yards |
Penalties and penalty yards |
away_turnovers |
Turnovers |
away_sacks |
Sacks |
away_third_down_conversions, away_third_down_attempts |
Third downs |
away_red_zone_attempts, away_red_zone_scores |
Red zone |
away_plays |
Plays (also total_plays) |
away_qb_name |
Quarterback name (text) |
away_qb_completions, away_qb_attempts, away_qb_yards |
Quarterback passing |
away_qb_interceptions, away_qb_passing_tds, away_qb_rushing_tds |
Quarterback interceptions and touchdowns |
Stats must use these snake_case names. A value that isn't a number is skipped.
How values are read
- Numbers can be sent as numbers (
14) or as text ("14"). - Quarter text is read loosely: "Q3", "3rd" and "third quarter" all become the 3rd quarter. "Halftime" keeps the quarter at 2nd; the feed can't show HALF.
- Distance from a full down-and-distance string works too: "3rd and 10" gives 10, and "1st and Goal" gives GOAL.
- Ball on keeps only the number. "MEM 38" and "38" both become the 38, because ScoreCastr can't tell which side of the 50 the text means.
- If a quarter or down can't be read, ScoreCastr keeps the value it already had.
Example body
{
"away_score": 14,
"home_score": 10,
"quarter": 3,
"clock": "8:42",
"down": 2,
"distance": 7,
"ball_on": 35,
"possession": "home",
"away_timeouts": 2,
"home_timeouts": 3
}
What the scorebug does on its own
ScoreCastr compares each update with the one before and plays the matching flag:
- A team's score goes up by 6: the touchdown flag. Up by 3: the field goal flag.
- Up by 2: the two-point conversion flag, but only if one of that team's offense stats (like passing yards or red zone scores) also went up in the same update.
- Timeouts go down: the timeout flag for that team.
- Penalties go up: the penalty flag for that team.
To get these, send running totals for the score and timeouts left, not the points of each play.
Fix common problems
Nothing changes. Check the field names letter for letter, and that the match's method is HTTP. The reply from the server tells you how many fields it used. See the Webhook API reference.
The possession arrow is wrong. Send away or home in lowercase. Other words aren't read.
The clock jumps around. Let one source run the clock: the feed, or the dashboard's clock buttons, not both.
A touchdown flag didn't play. The score has to go up by exactly 6 in one update. If the extra point arrives in the same update (+7), no flag plays.
Checklist
- Pro plan, webhook enabled with HTTP Client (Webhooks)
- Webhook URL copied into your sender
- Field names match this page exactly
- Clock sent as MM:SS or seconds
- Possession sent as away or home
- Scores and timeouts sent as running totals