> ## Documentation Index > Fetch the complete documentation index at: https://huddleup-sports.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint > `url` must be HTTPS. `events` empty or omitted = subscribe to **all** events; unknown names → `400 unknown_event:`. The endpoint's `source` is derived from your key, and it receives events only for leagues in your scope. The signing `secret` (`whsec_…`) is returned **in this response only** — store it immediately; it cannot be retrieved again, and there is no rotation endpoint (delete and re-register to rotate). ## OpenAPI ````yaml /api-reference/openapi.json post /webhooks openapi: 3.1.0 info: title: Whistle Partner API version: 1.0.0 summary: >- Server-to-server REST API for Whistle — post games, manage officials, track payouts. description: >- Whistle's v1 partner API lets league management systems and partner automations create leagues and games, add and assign sports officials, read the payout ledger, and receive webhooks. All requests require a partner API key (`Authorization: Bearer whk_…`). Responses use a consistent envelope: success is `{"data": …}`, failure is `{"error": ""}`. **Scoping:** partner keys are bound to a `source` namespace. A key reads and mutates only leagues whose `source` matches (plus leagues explicitly granted to it), and webhook endpoints it registered. Out-of-scope resources answer `404` identically to nonexistent ones — "not yours" and "not there" are deliberately indistinguishable. Write `source` is derived from the key: omit the field or echo your own value; any other value returns `400 source_mismatch`. **Contract stability:** v1 response field shapes, status strings, and webhook event names are additive-only. Breaking changes ship as `/api/v2` — v1 is never mutated in place. **Idempotency:** `source` + `externalId` form the upsert key on leagues, games, and officials. Re-posting the same `(source, externalId)` updates instead of duplicating. Re-using a game `externalId` under a different league returns `409 external_id_conflict`. **Money:** requests take dollars (`payDollars`); responses return both integer cents (`payCents`, `amountCents`) and dollars. **Time:** all timestamps are ISO 8601 UTC (`2026-07-09T18:00:00.000Z`). List endpoints are not paginated and take no filter parameters (except `?limit=` on webhook deliveries). The API has no CORS support — it is server-to-server only. contact: name: HuddleUp Sports support email: tommy@huddleup-sports.com url: https://huddleup-sports.com/docs/developers servers: - url: https://whistle.huddleup-sports.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Index description: Self-describing API index - name: Leagues description: Create, read, and update leagues - name: Games description: Batch-import games, read, update, cancel - name: Officials description: Add, approve, list, and remove officials; assign them to games - name: Assignments description: Who is covering which game - name: Payments description: Read-only payout ledger - name: Webhooks description: Register endpoints and inspect deliveries paths: /webhooks: post: tags: - Webhooks summary: Register a webhook endpoint description: >- `url` must be HTTPS. `events` empty or omitted = subscribe to **all** events; unknown names → `400 unknown_event:`. The endpoint's `source` is derived from your key, and it receives events only for leagues in your scope. The signing `secret` (`whsec_…`) is returned **in this response only** — store it immediately; it cannot be retrieved again, and there is no rotation endpoint (delete and re-register to rotate). operationId: registerWebhook requestBody: required: true content: application/json: schema: type: object required: - url properties: url: type: string format: uri description: HTTPS only. events: type: array items: $ref: '#/components/schemas/WebhookEventName' description: Empty/omitted = all events. source: type: string maxLength: 40 description: >- Derived from your key — omit, or echo your key's source; any other value returns 400 source_mismatch. example: url: https://example.com/whistle/webhooks events: - game.created - position.claimed - payment.paid responses: '201': description: Created endpoint including the once-only secret content: application/json: schema: type: object properties: data: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object properties: secret: type: string description: whsec_ + 48 hex chars. Returned once, never again. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: WebhookEventName: type: string enum: - game.created - game.updated - game.cancelled - game.completed - position.claimed - position.released - payment.paid - payment.failed - official.joined - official.approved - official.removed - official.no_show WebhookEndpoint: type: object properties: id: type: string url: type: string events: type: array items: $ref: '#/components/schemas/WebhookEventName' description: Empty array = subscribed to all events. active: type: boolean source: type: - string - 'null' createdAt: type: string format: date-time required: - id - url - events - active - source - createdAt Error: type: object required: - error properties: error: type: string description: >- snake_case error code. Two codes carry a parameter suffix: `invalid_startsAt:` and `unknown_event:`. responses: BadRequest: description: >- Validation failure. The body is `{"error":""}` with a single snake_case code (no details object). Codes include: `invalid_json`, `name_required`, `source_reserved`, `source_mismatch` (body `source` differs from your key's — omit the field), `no_games`, `too_many_games`, `invalid_startsAt:`, `invalid_startsAt`, `invalid_status`, `externalId_required`, `positionId_required`, `https_url_required`, `unknown_event:`, `create_failed`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_json Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized securitySchemes: bearerAuth: type: http scheme: bearer description: >- Partner API key: `Authorization: Bearer whk_…`. Keys are issued by the Whistle team (email tommy@huddleup-sports.com), shown once at issuance, and bound to your `source` namespace — they access only your leagues (plus explicit grants) and your webhook endpoints. Any auth failure returns `401 {"error":"unauthorized"}`; the API never returns 403 — out-of-scope resources answer 404 exactly like nonexistent ones. ````