Skip to main content
POST
/
webhooks
/
{id}
/
rotate-secret
curl -X POST https://teambattles.gg/api/v1/webhooks/wh_abc123/rotate-secret \
  -H "Authorization: Bearer tb_your_api_key"

{
  "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 {id} must resolve to an endpoint in your key’s own derived scope (user, game, or league, depending on your key type). An endpoint owned by another scope - or an unknown id - is reported as 404 error_webhook_not_found.

​
What’s Returned

Returns { id, signingSecret, secretPrefix }. signingSecret is the new plaintext secret and secretPrefix is its first 8 chars (display only). Rotating also resets the endpoint’s failure count.
The new signingSecret is shown once by this response and is never returned again. Store it securely now.
The previous secret keeps signing deliveries for a 24-hour grace window after rotation, so your consumers can roll over to the new secret without missing or rejecting deliveries. Verify signatures against both secrets until you have finished updating, then drop the old one. For the full signature scheme and header details, see the Webhooks guide.
curl -X POST https://teambattles.gg/api/v1/webhooks/wh_abc123/rotate-secret \
  -H "Authorization: Bearer tb_your_api_key"

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
id
string
required

Webhook endpoint id.

Response

The new 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.