Skip to main content
Generate a fresh webhook signing secret for the organization. The new secret is returned exactly once in the response — Tumban does not expose it via Get org settings. 
POST /api/v2/org/webhook-secret/rotate
The canonical path is /api/v2/org/webhook-secret/rotate — the /org/ segment is required. POST /api/v2/webhook-secret/rotate (without /org/) does not exist and will return 404.

​
Storage model

Unlike API keys (which Tumban stores only as a SHA-256 hash), the webhook secret is retained in plaintext on the server. Tumban needs the raw value on every webhook delivery to compute the HMAC signature. Because the secret is shown to you exactly once at rotation time and never reappears in GET /api/v2/org/settings, there is no recovery path — store the value immediately when this endpoint returns it. If you lose it, rotate again and update every verifier in lockstep.

​
Permissions

Rotating the webhook secret requires an admin role on a dashboard session. Members and API-key auth are rejected with 403.
CallerAllowed
Dashboard session, role=adminYes
Dashboard session, role=memberNo — 403 Admin role required
API key (sk_…)No — 403

​
Request body

None.

​
Response

​
webhook_secret
string
required
The new secret (64-character hex string). Use it to verify the signature on incoming webhooks. See Signature verification.
​
rotated_at
string
required
ISO 8601 UTC timestamp.

​
Example

curl -X POST https://api-v2.tumban.com/api/v2/org/webhook-secret/rotate \
  -H "Authorization: Bearer <session-token>"

{
  "webhook_secret": "5f4dcc3b5aa765d61d8327deb882cf99...",
  "rotated_at": "2026-04-29T12:00:00.123456+00:00"
}
Update your verification code before rotating, or accept a brief window where signatures will not verify. Tumban signs every new webhook with the current secret only — old secrets become inactive immediately.

​
Using the dashboard

1

Open Webhooks

From the sidebar, click Webhooks.
2

Rotate the secret

In the Webhook Secret tile, click Rotate Secret. The description on the tile explains: “Used to verify incoming webhook payloads. Rotating immediately invalidates the old secret — update your server before rotating.”
3

Copy the new secret

The new secret appears once with the prompt “New secret — copy it now. It won’t be shown again.” Click Copy and store it in your secret manager.
Non-admins do not see the Rotate Secret control.