---
title: "Register a webhook subscription (Edge+)"
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Register a webhook subscription (Edge+)

`POST /v1/webhooks`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/webhooks`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates an HTTPS webhook on an Edge-or-higher API key with webhook:write scope. The HMAC secret is returned exactly once. Delivery is at least once and uses X-BBS-Signature: t=<unix>,v1=<hex>, where the HMAC-SHA256 input is "t.raw_body". Non-2xx responses are retried after 30s, 2m, 10m, and 1h (five attempts total).

## Request body

- WebhookRegistration
  - `id` string
  - `url` string, uri, required
  - `events` string[], required
  - `secret` string: HMAC-SHA256 secret. Shown once at creation.
  - `createdAt` string, date-time
  - `enabled` boolean
  - `consecutiveFailures` integer
  - `parkedAt` string, date-time, nullable
  - `parkedReason` string, nullable

## Response `201`

created; secret is present only in this response

## Other responses

- `400`: invalid event list or unsafe destination URL
- `403`: Edge-or-higher plan and webhook:write scope required

---

[API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/9191fc13fcdb?raw)