curl --request POST \
--url https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "01960000-0000-4000-8000-000000000e5d",
"url": "https://api.example.test/hooks/vumasign",
"subscribed_events": [
"envelope.completed",
"envelope.declined"
],
"brand_id": null,
"environment": "live",
"active": true,
"consecutive_failures": 0,
"last_success_at": "2026-09-02T09:06:00.000Z",
"last_failure_at": null,
"disabled_at": null,
"disabled_reason": null,
"created_at": "2026-09-01T08:00:00.000Z",
"secret": "whsec_specimen_rotated_secret_never_use_000000000"
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Mint a new signing secret, keeping the old one alive briefly.
THE SECOND AND LAST TIME A SECRET IS RETURNED.
⚠️ THE OLD SECRET KEEPS WORKING FOR 24 HOURS, and during that window every delivery carries BOTH signatures — v1 under the new secret and v0 under the old. That is what makes rotation a deploy you can take your time over rather than an outage: without it, every delivery between our rotation and your release would be unverifiable, and a receiver doing the correct thing would drop real events for the whole gap.
Deploy the new secret, then do nothing — v0 expires on its own.
⚠️ IF THE OLD SECRET LEAKED, ROTATE TWICE. previous_secret holds whatever the current secret held a moment ago, so a second rotation displaces the leaked value immediately. It is the only way to end the window early, and nobody would guess it.
⚠️ A SUB-RESOURCE RATHER THAN A PATCH, because this is an act with consequences rather than a property assignment: it invalidates what you have deployed, starts a clock, and returns a credential once. There is no Idempotency-Key here and a retry rotates twice — but the RESPONSE is the secret, so “I do not know which state I am in” is not reachable: the live secret is the last one you successfully received.
200 rather than 201: nothing was created, and the endpoint keeps its id.
curl --request POST \
--url https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/webhooks/{webhookId}/rotate-secret"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "01960000-0000-4000-8000-000000000e5d",
"url": "https://api.example.test/hooks/vumasign",
"subscribed_events": [
"envelope.completed",
"envelope.declined"
],
"brand_id": null,
"environment": "live",
"active": true,
"consecutive_failures": 0,
"last_success_at": "2026-09-02T09:06:00.000Z",
"last_failure_at": null,
"disabled_at": null,
"disabled_reason": null,
"created_at": "2026-09-01T08:00:00.000Z",
"secret": "whsec_specimen_rotated_secret_never_use_000000000"
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Authorizations
Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.
Path Parameters
Response
The endpoint, and the new secret — for the only time. The response also carries Vumasign-Previous-Secret-Expires-In, in seconds.
The endpoint and its new secret.
What this endpoint hears about. Never empty. ⚠️ An unknown name is refused at registration rather than accepted and never delivered.
One event type.
envelope.sent, envelope.completed, envelope.declined, envelope.voided, envelope.expired, envelope.sealed, envelope.sealing_failed, recipient.completed, recipient.verification_locked, recipient.identity_check_failed, recipient.identity_verified, recipient.delegated, authorisation.invited, authorisation.granted, authorisation.declined, authorisation.invite_expired, authorisation.cancelled, authorisation.revoked, authorisation.invalidated, authorisation.expired, authorisation.expiring, authorisation.renewal_requested, template.named Deliver only envelopes carrying this brand; null for every envelope in the organisation.
⚠️ THIS IS ROUTING, NOT ISOLATION. Any key on this organisation can read every envelope in it whatever brand it carries — there is no brand predicate in any access rule anywhere. Filtering decides which events are POSTed to which URL; it does not, and cannot, stop a consumer learning about another brand by asking. Do not build a permission boundary out of it.
An envelope sent with no brand — by an organisation that has none — reaches only the endpoints with no filter. See Brands.
Which events this endpoint receives: live only those whose body says sandbox: false, test only those that say sandbox: true, both either. The words are the API key environments, vsk_live_ and vsk_test_. An event with no environment — template.named — reaches every endpoint whatever this says.
Endpoints registered before this setting existed are both. Changing it re-routes the next event, not deliveries already queued.
⚠️ ROUTING, NOT ISOLATION, like brand_id: it decides what is POSTed here, not what any key may read.
live, test, both