Webhooks

Overview

Webhooks deliver HTTP POST requests to your server when game events occur. Instead of polling the API, you register an endpoint URL and subscribe to the event types you care about. When an event fires, we send a signed JSON payload to your URL.

Manage webhooks through the dashboard or programmatically via API key. The full API is covered by an OpenAPI spec — hand it to your AI coding agent and let it handle setup, monitoring, and receiver scaffolding.

Plan Limits

Event Types

Events are namespaced by sport (nba.*, mlb.*, nhl.*, ncaab.*, ncaaw.*). A single endpoint can subscribe to events from multiple sports.

NBA

MLB

NHL

NCAAB

NCAAW

Event Payloads

Each delivery sends a JSON body directly as the HTTP POST body. The event_type field is included at the top level of every payload. Event metadata (ID, timestamp, signature) is sent via headers, not in the body.

Game-Only Events

Events: nba.game.started, nba.game.ended, nba.game.overtime, mlb.game.started, mlb.game.ended, mlb.game.extra_innings, nhl.game.started, nhl.game.ended, nhl.game.overtime, ncaab.game.started, ncaab.game.ended, ncaab.game.overtime

{
  "event_type": "nba.game.started",
  "game": {
    "id": 12345
  }
}

NBA Period Ended

Event: nba.game.period_ended

{
  "event_type": "nba.game.period_ended",
  "game": {
    "id": 12345
  },
  "ended_period": 2
}

MLB Inning Half Ended

Event: mlb.game.inning_half_ended

{
  "event_type": "mlb.game.inning_half_ended",
  "game": {
    "id": 67890
  },
  "inning": 5,
  "inning_half": "top"
}

MLB Inning Ended

Event: mlb.game.inning_ended

{
  "event_type": "mlb.game.inning_ended",
  "game": {
    "id": 67890
  },
  "inning": 5
}

NBA Player Events

Events: nba.player.scored, nba.player.rebound, nba.player.assist, nba.player.steal, nba.player.block, nba.player.foul, nba.player.turnover

{
  "event_type": "nba.player.scored",
  "game": {
    "id": 12345
  },
  "play": {
    "type": "Made Shot",
    "text": "LeBron James makes driving layup",
    "score_value": 2,
    "period": 3,
    "clock": "4:32",
    "home_score": 78,
    "away_score": 72
  },
  "player": {
    "id": 678,
    "first_name": "LeBron",
    "last_name": "James",
    "position": "F",
    "team_id": 14
  }
}

MLB Batter Events

Events: mlb.batter.hit, mlb.batter.home_run, mlb.batter.strikeout, mlb.batter.walk, mlb.batter.hit_by_pitch

{
  "event_type": "mlb.batter.home_run",
  "game": {
    "id": 67890
  },
  "play": {
    "type": "Home Run",
    "text": "Aaron Judge homers (25) on a fly ball to left center field.",
    "score_value": 1,
    "inning": 5,
    "inning_half": "top",
    "home_score": 3,
    "away_score": 2
  },
  "batter": {
    "id": 456,
    "first_name": "Aaron",
    "last_name": "Judge",
    "team_id": 10
  },
  "pitcher": {
    "id": 789,
    "first_name": "Brayan",
    "last_name": "Bello",
    "team_id": 15
  }
}

MLB Team Scoring

Event: mlb.team.scored

{
  "event_type": "mlb.team.scored",
  "game": {
    "id": 67890
  },
  "play": {
    "type": "Scoring Play",
    "text": "Aaron Judge homers (25) on a fly ball to left center field.",
    "score_value": 1,
    "inning": 5,
    "inning_half": "top",
    "home_score": 3,
    "away_score": 2
  },
  "team_id": 10
}

NHL Period Ended

Event: nhl.game.period_ended

{
  "event_type": "nhl.game.period_ended",
  "game": {
    "id": 178532
  },
  "ended_period": 2
}

NHL Player Events

Events: nhl.player.goal, nhl.player.assist, nhl.player.shot

{
  "event_type": "nhl.player.goal",
  "game": {
    "id": 178532
  },
  "play": {
    "type": "goal",
    "period": 2,
    "period_type": "REG",
    "time_in_period": "14:22",
    "time_remaining": "05:38",
    "home_score": 3,
    "away_score": 1
  },
  "player": {
    "id": 1234,
    "first_name": "Connor",
    "last_name": "McDavid",
    "position": "C",
    "team_id": 56
  }
}

NHL Penalty

Event: nhl.player.penalty

{
  "event_type": "nhl.player.penalty",
  "game": {
    "id": 178532
  },
  "play": {
    "type": "penalty",
    "period": 1,
    "period_type": "REG",
    "time_in_period": "08:15",
    "time_remaining": "11:45",
    "home_score": 1,
    "away_score": 0,
    "penalty_type": "tripping",
    "penalty_minutes": 2
  },
  "player": {
    "id": 9012,
    "first_name": "Tom",
    "last_name": "Wilson",
    "position": "RW",
    "team_id": 23
  }
}

NHL Team Goal

Event: nhl.team.goal

{
  "event_type": "nhl.team.goal",
  "game": {
    "id": 178532
  },
  "play": {
    "type": "goal",
    "period": 2,
    "period_type": "REG",
    "time_in_period": "14:22",
    "time_remaining": "05:38",
    "home_score": 3,
    "away_score": 1
  },
  "team_id": 56,
  "scorer": {
    "id": 1234,
    "first_name": "Connor",
    "last_name": "McDavid",
    "position": "C",
    "team_id": 56
  }
}

NCAAB Period Ended

Event: ncaab.game.period_ended

{
  "event_type": "ncaab.game.period_ended",
  "game": {
    "id": 401638901
  },
  "ended_period": 1
}

NBA Injury Events

Events: nba.injury.created, nba.injury.updated, nba.injury.cleared

Injury events are not tied to a specific game. They fire whenever the NBA injury report changes — a player is added, their status changes, or they are cleared. The created and updated events include current injury details, while updated and cleared include the previous injury for diffing.

{
  "event_type": "nba.injury.created",
  "player": {
    "id": 678,
    "first_name": "LeBron",
    "last_name": "James",
    "position": "F",
    "team_id": 14
  },
  "injury": {
    "status": "Out",
    "description": "Left ankle sprain",
    "return_date": "2026-03-15"
  }
}

{
  "event_type": "nba.injury.updated",
  "player": {
    "id": 678,
    "first_name": "LeBron",
    "last_name": "James",
    "position": "F",
    "team_id": 14
  },
  "injury": {
    "status": "Doubtful",
    "description": "Left ankle sprain",
    "return_date": "2026-03-20"
  },
  "previous_injury": {
    "status": "Out",
    "description": "Left ankle sprain",
    "return_date": "2026-03-15"
  }
}

{
  "event_type": "nba.injury.cleared",
  "player": {
    "id": 678,
    "first_name": "LeBron",
    "last_name": "James",
    "position": "F",
    "team_id": 14
  },
  "previous_injury": {
    "status": "Doubtful",
    "description": "Left ankle sprain",
    "return_date": "2026-03-20"
  }
}

NCAAB Player Events

Events: ncaab.player.scored, ncaab.player.rebound, ncaab.player.assist, ncaab.player.steal, ncaab.player.block, ncaab.player.foul, ncaab.player.turnover

{
  "event_type": "ncaab.player.scored",
  "game": {
    "id": 401638901
  },
  "play": {
    "type": "Made Shot",
    "text": "Cooper Flagg makes driving layup",
    "score_value": 2,
    "period": 1,
    "clock": "12:45",
    "home_score": 14,
    "away_score": 10
  },
  "player": {
    "id": 5678,
    "name": "Cooper Flagg",
    "position": "F",
    "team_id": 150
  }
}

Webhook Headers

Every delivery includes the following headers:

Signature Verification

Verify that webhook deliveries are authentic by computing an HMAC-SHA256 signature and comparing it to the X-BDL-Webhook-Signature header.

1. Extract the timestamp from X-BDL-Webhook-Timestamp
2. Construct the signed message: {timestamp}.{raw_body}
3. Compute HMAC-SHA256 using your endpoint secret
4. Compare against the signature (after the v1= prefix) using a constant-time comparison

JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, headers, secret) {
  const timestamp = headers['x-bdl-webhook-timestamp'];
  const signature = headers['x-bdl-webhook-signature'];

  const message = `${timestamp}.${payload}`;
  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, headers: dict, secret: str) -> bool:
    timestamp = headers['x-bdl-webhook-timestamp']
    signature = headers['x-bdl-webhook-signature']

    message = f"{timestamp}.{payload.decode()}"
    expected = 'v1=' + hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Retries & Auto-disable

If your endpoint returns a non-2xx status code or the request times out (30s), the delivery is retried with exponential backoff:

Free accounts get 3 total attempts (initial + 2 retries). ALL-ACCESS accounts get 5 total attempts (initial + 4 retries).

Delivery Statuses

Getting Started

1. Sign up at app.balldontlie.io
2. Navigate to the Webhooks tab in your dashboard
3. Create an endpoint with your URL and desired event types
4. Send a test event to verify your endpoint is receiving payloads
5. Store your signing secret securely and implement signature verification

AI & Agents

The Webhooks API is fully programmable via API key, which means AI coding agents can manage your entire webhook lifecycle — creating endpoints, subscribing to events, building receivers, and monitoring delivery health — without you touching the dashboard.

OpenAPI Specification

Give your agent the Webhooks OpenAPI spec and it has everything it needs to work with the API: endpoint schemas, authentication, request/response formats, and event type definitions.

Download webhooks-openapi.yml

What an Agent Can Do

1. Set up endpoints — create webhook endpoints pointed at your server URL and subscribe to the event types you need
2. Scaffold a receiver — generate a server (Express, Flask, FastAPI, etc.) that accepts webhook POSTs, verifies signatures, and routes events by type
3. Monitor health — check GET /webhooks/v1/usage for delivery counts and GET /webhooks/v1/endpoints/:id/deliveries?status=failed for failures
4. Self-heal — retry failed deliveries, rotate secrets, re-enable disabled endpoints, and adjust event subscriptions

Example Prompt

Paste this into your AI coding tool (Claude Code, Cursor, Windsurf, Copilot, etc.) to get started:

I want to receive real-time NBA scoring alerts via BALLDONTLIE webhooks.

Here is the API spec: https://www.balldontlie.io/webhooks-openapi.yml
My API key is: $BALLDONTLIE_API_KEY

Please:
1. Create a webhook endpoint at https://my-server.com/webhooks/bdl
   subscribed to nba.player.scored and nba.game.ended
2. Write an Express.js server that:
   - Accepts POST /webhooks/bdl
   - Verifies the HMAC-SHA256 signature using the endpoint secret
   - Logs a message for each scoring play with the player name and score
   - Returns 200 on success
3. Send a test event to verify it works

Tips for Agent Workflows

• The OpenAPI spec includes all 55+ event types. Point your agent at GET /webhooks/v1/event-types to discover which events are available for your subscription tier.
• Store the secret from the create endpoint response immediately — it is only returned on creation and on POST /rotate-secret.
• Use POST /endpoints/:id/test to send a test event and verify your receiver before live games start.
• Agents can build event-driven automations on top of webhooks: Discord bots, Slack alerts, SMS notifications, database pipelines, betting triggers, and more.