An NFL injury API with webhooks
Quick answer: GridIron Data pushes NFL injury status changes to one HTTPS URL as signed JSON, within a few minutes of a change on ESPN's injury report. Register it with POST /webhooks, verify the X-GridIron-Signature header, and answer 2xx within 5 seconds. Webhooks and the polling feed /injuries/changes need Pro ($29 a month or $249 a year). A free key still returns each player's current injury_status.
- Delivery
- Signed HTTPS POST
- Checked
- Every 2 min, 8am-1am ET
- Retries
- 2, after 1s and 4s
- Plan
- Pro
How do I register a webhook?
One call, or use Injury Change Webhook on your dashboard. Each account has one webhook. The URL must be HTTPS on port 443 and resolve to public addresses. The first registration answers 201 with a signing_secret (whsec_...) that is shown only once.
curl -X POST -H "x-api-key: YOUR_PRO_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.com/gridiron"}' \
"https://api.gridirondata.com/api/v1/webhooks"
# Send yourself a test event
curl -X POST -H "x-api-key: YOUR_PRO_KEY" \
"https://api.gridirondata.com/api/v1/webhooks/test"Webhook deliveries and these management calls never count against your monthly requests.
What does the webhook send?
A POST with X-GridIron-Event, X-GridIron-Event-Id, X-GridIron-Timestamp and X-GridIron-Signature headers. A run with more than 250 changes is split into numbered parts.
{
"id": "evt_3f1c2a9b8d7e6f5a4b3c2d1e",
"type": "injury.changes",
"created_at": "2026-10-25T17:00:09Z",
"season": "2026",
"detected_at": "2026-10-25T17:00:05Z",
"count": 1,
"part": 1,
"parts": 1,
"changes": [{
"player_id": "Josh Allen#QB",
"player_name": "Josh Allen",
"position": "QB",
"team": "BUF",
"previous_status": "Questionable",
"status": "Out",
"detected_at": "2026-10-25T17:00:05Z",
"source": "espn"
}]
}
How do I verify and handle it?
The signature is sha256= plus the hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with your secret. Compute it over the raw bytes, compare in constant time and reject old timestamps. Event ids are stable, so use them to drop a retry.
import hashlib, hmac, json, os, time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["GRIDIRON_WEBHOOK_SECRET"] # whsec_..., shown once
seen = set() # use Redis or a table in production
@app.post("/gridiron")
def gridiron():
ts = request.headers.get("X-GridIron-Timestamp", "0")
raw = request.get_data()
expected = "sha256=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + raw,
hashlib.sha256).hexdigest()
if (not ts.isdigit() or abs(time.time() - int(ts)) > 300
or not hmac.compare_digest(expected, request.headers.get("X-GridIron-Signature", ""))):
abort(401)
event = json.loads(raw)
if event["id"] in seen: # a retry of something already handled
return "", 204
seen.add(event["id"])
for c in event.get("changes", []):
print(f'{c["player_name"]} ({c["team"]}): {c["previous_status"]} -> {c["status"]}')
return "", 204
What happens when my endpoint fails?
Timeouts, connection errors, 408, 429 and 5xx answers are retried twice, after 1 and 4 seconds. Other 4xx answers are not retried and redirects are not followed. After 5 failed deliveries in a row the webhook is disabled; fix the endpoint and save the URL again to turn it back on. Full rules are in the webhook docs.
Webhook or polling?
| Webhook | Polling /injuries/changes | |
|---|---|---|
| You need | A public HTTPS endpoint | A cron job or a loop |
| Requests used | None | About 6,100 a month at every 5 minutes, 8am-1am ET |
| Missed a change? | Retried twice, then read the feed | since cursor picks up where you left off (14-day lookback) |
| Best for | Alerts, bots, live apps | Scripts and anything behind a firewall |
The injury changes guide has a full polling script, and the Discord bot page has a relay that posts alerts to a channel.
Frequently asked questions
Is there a free NFL injury API?
A free GridIron Data key returns each player's current injury status from the player lookups, 250 requests a month. The change feed and webhooks, which tell you what just changed, need Pro at $29 a month or $249 a year.
How fast are injury webhooks?
GridIron checks ESPN's league-wide injury report every 2 minutes from 8:00 am to 1:00 am ET and every 10 minutes overnight. A change is sent within a few minutes of appearing there.
Can a webhook post straight to Discord or Slack?
Not directly. The body is GridIron's JSON, so point it at a small relay that verifies the signature and then posts to your channel.
Does the feed include offensive linemen?
Yes. Offensive linemen are on Pro and appear in the injury changes feed.