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,
"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,
"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
The endpoint’s id, as returned when it was registered.
An endpoint id.
"01960000-0000-4000-8000-000000000e5d"
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.
The endpoint’s id. A bare uuid.
Where deliveries are POSTed. https:// only, no credentials, and not a private or loopback address — deliveries are made from inside our network.
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 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.
Whether we are delivering. False either because you deactivated it or because it was auto-disabled after failing for the whole health window — disabled_reason says which, in prose.
⚠️ DELIVERIES THAT EXHAUSTED THE WHOLE LADDER SINCE THE LAST SUCCESS, not individual attempts. One unreachable host over one event counts once here, not seven times.
The last 2xx we received. Null if there has never been one.
The last delivery that used up its ladder.
When delivery stopped. Null while active.
Why, in prose for a person. Null while active. ⚠️ This is the field that answers "why did my endpoint stop receiving events" without a support ticket.
ISO 8601, UTC.
⚠️ SHOWN ONCE, HERE. This is the key the Vumasign-Signature header is computed under. Treat it as a credential: it is not in any log of ours and it must not be in one of yours.