Skip to main content
POST
/
webhooks
curl -X POST https://teambattles.gg/api/v1/webhooks \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/teambattles","events":["match.completed","score.confirmed"],"label":"Prod match feed"}'

{
  "id": "<string>",
  "signingSecret": "<string>",
  "secretPrefix": "<string>"
}

​
Permission Required

This endpoint requires the webhooks.manage permission (the { kind: "webhook" } scope) on your API key, plus the webhooks feature. Webhooks are gated to api_pro or higher plans: a key on a free plan receives 403 error_api_feature_required.

​
Access / Membership Rules

Webhooks are owner-scoped. The new endpoint is created in your key’s own derived scope: a personal key creates it in your user scope, a game-developer key in its bound game, and a league-operator key in its bound league. The scope is never a request field. The url must be an HTTPS endpoint - private, loopback, and cloud-metadata hosts are rejected.

​
What’s Returned

Returns 201 with { id, signingSecret, secretPrefix }. id is the new endpoint id, secretPrefix is the first 8 chars of the signing secret (display only), and signingSecret is the full plaintext secret.
The signingSecret is shown once at creation and is never returned again. Store it securely now - if you lose it, rotate the secret to mint a new one.

​
Request Body

FieldTypeRequiredDescription
urlstringYesHTTPS delivery URL. Private, loopback, and metadata hosts are rejected.
eventsstring[]YesAt least one event token: exact catalog names (e.g. match.completed) or family wildcards (e.g. match.*).
labelstringNoOptional human-readable label for the endpoint.
Use the signing secret to verify the Standard Webhooks webhook-id / webhook-timestamp / webhook-signature headers (the X-TeamBattles-Event header carries the event name). For the full signature scheme and event catalog, see the Webhooks guide.
curl -X POST https://teambattles.gg/api/v1/webhooks \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/teambattles","events":["match.completed","score.confirmed"],"label":"Prod match feed"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Body

application/json

Create a webhook endpoint in the caller's scope.

​
url
string
required

HTTPS endpoint URL. Private/loopback/metadata hosts are rejected.

​
events
string[]
required

Subscribed event tokens: exact catalog names (e.g. match.completed) or family wildcards (e.g. match.*). At least one required.

Minimum array length: 1
​
label
string

Optional human label for the endpoint.

Response

The created endpoint's id and one-time signing secret.

One-time signing-secret reveal (create/rotate).

​
id
string
required

The endpoint id the secret belongs to.

​
signingSecret
string
required

Plaintext signing secret. Shown ONCE - store it now.

​
secretPrefix
string
required

First 8 chars of the new signing secret.