Skip to main content
POST
Rotate the signing secret for a webhook
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/webhooks/rotate-secret Mint a new signing secret for an existing webhook subscription. X-Forge-Signature-V2 uses the new secret from the next delivery. Until previousSecretExpiresAt (at least 24 hours on), webhook-signature also carries a signature made with the replaced secret, so a receiver can deploy the new secret without dropping a delivery. A second rotation inside that window replaces the replaced secret: at most two are ever live. To end a leaked secret’s validity at once, revoke the subscription instead. See Rotating the secret.

Authentication

External App credential. Requires permission webhooks:manage.

Request body

string
required
The subscription ID (Convex webhookSubscriptions document ID).

Responses

string
The new HMAC signing secret. Returned exactly once — capture it and store in a secrets manager immediately.
string
ISO 8601 time until which the replaced secret still signs webhook-signature, beside the new one.
string
Reminder string emphasizing the secret will not be shown again.
The new secret is returned exactly once. Forge stores it encrypted on the subscription (needed to sign deliveries) but will not re-emit it, and never stores this response for Idempotency-Key replay. Capture it from this response and store it in a secrets manager immediately; if it is lost, rotate again.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

webhookId
string
required

Webhook subscription ID

Response

New secret, shown once

data
object
required
meta
object
required