/v1/data/live/notify

Registers your callback URL for LIVE notifications. On success the response has no body; the new notify id is returned in the X-ShotTracker-Notify-Id header. End notifications are disabled by default (end_notification: false); call Enable LIVE End Notify if you also want state=END callbacks.

The url query parameter is required and must be URL-encoded. Use a base path with no query string. Only one LIVE notify is allowed per consumer.

Designing your callback endpoint

ShotTracker invokes your registered URL with an HTTP PUT when a live practice drill, practice, game round, or game starts (and optionally ends). Your service must expose a publicly reachable HTTPS endpoint that accepts that call.

Request ShotTracker sends

PUT {your-registered-url}?notify_id={notify id}&action=LIVE&data={id}&state={START|END}&type={SESSION|GAME|PRACTICE}

• Method is always PUT
• Request body is empty
• ShotTracker does not send HMAC or other auth headers on the callback; secure the URL yourself (path secret, network controls, etc.)
• Query parameters are appended with ?. Register a URL without an existing query string (for example https://hooks.example.com/shottracker/live)

Example: PUT https://hooks.example.com/shottracker/live?notify_id=abc-123&action=LIVE&data=45a64b38-b205-11ed-b27e-0242e9e2912e&state=START&type=GAME

How your callback should behave

1. Accept PUT on the exact path you registered.
2. Respond quickly. ShotTracker uses short connect (~500 ms) and read (~1000 ms) timeouts. Acknowledge immediately (for example 204 No Content or 200 OK) and do heavier work asynchronously.
3. Parse query parameters (notify_id, action, data, state, type). Use data with type to decide what to fetch next from the Event API (subscribe, search, catch-up, WebSocket, and so on).
4. Treat the call as a signal, not a data payload. The callback does not include stats or box score; it tells you that something started or ended so you can call the Event API.
5. Be idempotent. The same logical event should not break your system if delivered more than once.
6. Failures are not retried. If your endpoint times out or returns an HTTP error, ShotTracker logs the failure and continues; it does not automatically retry that notification.

Minimal Node.js callback (see also Code examples):

const http = require("http"); const { URL } = require("url"); http.createServer((req, res) => { if (req.method !== "PUT") { res.writeHead(405); return res.end(); } const url = new URL(req.url, "http://localhost"); const notifyId = url.searchParams.get("notify_id"); const data = url.searchParams.get("data"); const state = url.searchParams.get("state"); const type = url.searchParams.get("type"); console.log({ notifyId, data, state, type }); res.writeHead(204); res.end(); }).listen(8080);

When notifies fire

SESSION covers period- or drill-level activity. GAME / PRACTICE cover the overall event lifecycle.

End notifications

When you create a notify, end_notification is false. You only receive state=START callbacks until you call Enable LIVE End Notify. Use Disable LIVE End Notify to turn END callbacks off again.

Registration rules

• Requires the consumer NOTIFY scope
• Only one LIVE notify may exist per consumer. Creating a second returns 422 with Notify action already exists
• You are notified only for live activity your credentials are authorized to access (team and/or court / facility access)
• URL-encode the url query parameter when registering or updating (for example https%3A%2F%2Fhooks.example.com%2Fshottracker%2Flive)