Webhooks

Webhooks let you receive real-time HTTP POST notifications when events occur — new picks scored, lines moving, picks settled, etc.

Available event types

curl -H "X-API-Key: $NBAV3_DATA_TOKEN" \
  https://nbaproplab.com/api/v1/data/events/types

Event	Fired when
picks.scored	New picks are generated after a scoring run
picks.settled	Picks are settled after game completion
lines.moved	A significant line movement is detected (≥ 0.75pt)
odds.refreshed	New odds snapshot ingested from sportsbooks

Creating a subscription

curl -X POST https://nbaproplab.com/api/v1/data/webhook-subscriptions \
  -H "X-API-Key: $NBAV3_DATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/nbaproplab",
    "events": ["picks.scored", "lines.moved"],
    "secret": "your-webhook-secret"
  }'

Webhook payload

Each webhook POST includes:

{
  "id": "evt_abc123",
  "type": "picks.scored",
  "timestamp": "2026-05-20T10:45:00Z",
  "data": {
    "count": 42,
    "date": "2026-05-20",
    "premiumCount": 8,
    "standardCount": 34
  }
}

Verifying signatures

Every webhook includes an X-Webhook-Signature header. Verify it with your secret:

import { createHmac } from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(body).digest('hex');
  return signature === `sha256=${expected}`;
}

Caution

Always verify webhook signatures before processing. Unverified webhooks could be spoofed by a third party.

Managing subscriptions

Action	Method	Endpoint
List	GET	/api/v1/data/webhook-subscriptions
Create	POST	/api/v1/data/webhook-subscriptions
Update	PATCH	/api/v1/data/webhook-subscriptions/{id}
Delete	DELETE	/api/v1/data/webhook-subscriptions/{id}
Test	POST	/api/v1/data/webhook-subscriptions/{id}/test

Retry policy

Failed deliveries (non-2xx response) are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 4 failed attempts, the subscription is marked as failing. It remains active but you’ll see a warning in your subscription list.