curl --request POST \
--url https://app.vumasign.com/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://api.example.test/hooks/vumasign",
"events": [
"envelope.completed",
"envelope.declined"
]
}
'import requests
url = "https://app.vumasign.com/api/v1/webhooks"
payload = {
"url": "https://api.example.test/hooks/vumasign",
"events": ["envelope.completed", "envelope.declined"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://api.example.test/hooks/vumasign',
events: ['envelope.completed', 'envelope.declined']
})
};
fetch('https://app.vumasign.com/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://api.example.test/hooks/vumasign\",\n \"events\": [\n \"envelope.completed\",\n \"envelope.declined\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
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": null,
"last_failure_at": null,
"disabled_at": null,
"disabled_reason": null,
"created_at": "2026-09-01T08:00:00.000Z",
"secret": "whsec_specimen_secret_never_use_this_value_000000"
}{
"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>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Register an endpoint and mint its signing secret.
THE ENDPOINT THAT MAKES MULTI-TENANT ONBOARDING PROGRAMMATIC. BoldSign has no webhook management API at all — theirs is configured in a dashboard, by a human — which means a customer who resells to their own tenants cannot onboard one without somebody clicking. This is the same resource with the same six methods every other noun gets.
⚠️ THE RESPONSE CARRIES secret AND NOTHING ELSE EVER WILL. Store it now. There is no “show me again”: if you lose it, rotate.
⚠️ NO Idempotency-Key, UNLIKE POST /api/v1/envelopes, and the difference is what a retry costs. A duplicated send emails a stranger twice and bills twice, and neither can be taken back; a duplicated registration emails nobody, bills nothing, is visible in a list of at most 10 and is one DELETE away.
See x-webhooks at the root of this document for the body we will POST, the signature, and the retry ladder.
curl --request POST \
--url https://app.vumasign.com/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://api.example.test/hooks/vumasign",
"events": [
"envelope.completed",
"envelope.declined"
]
}
'import requests
url = "https://app.vumasign.com/api/v1/webhooks"
payload = {
"url": "https://api.example.test/hooks/vumasign",
"events": ["envelope.completed", "envelope.declined"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://api.example.test/hooks/vumasign',
events: ['envelope.completed', 'envelope.declined']
})
};
fetch('https://app.vumasign.com/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://api.example.test/hooks/vumasign\",\n \"events\": [\n \"envelope.completed\",\n \"envelope.declined\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
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": null,
"last_failure_at": null,
"disabled_at": null,
"disabled_reason": null,
"created_at": "2026-09-01T08:00:00.000Z",
"secret": "whsec_specimen_secret_never_use_this_value_000000"
}{
"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>"
}
}{
"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.
Body
Where to deliver, what to deliver, and optionally which brand only.
The registration.
At least one event type. ⚠️ An empty array is refused rather than read as "everything": an endpoint subscribed to nothing is a support ticket, and this API already has one place where an empty list means "all" (an API key’s scopes) — two opposite readings of an empty array is how somebody eventually gets one of them wrong. Duplicates are collapsed.
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 Optional, default null. Filter deliveries to one brand. ⚠️ ROUTING, NOT ISOLATION — see the property of the same name on the endpoint.
Copy the id from Settings → Brands in the dashboard. An archived brand’s id is accepted here, unlike on an envelope create: envelopes already sent under it go on producing events.
null
Optional. Which events this endpoint receives: live, test or both. ⚠️ OMITTED, IT IS THE ENVIRONMENT OF THE KEY YOU REGISTER WITH: a vsk_test_ key registers a test endpoint and a vsk_live_ key a live one. Send both for one URL that hears every event. null is refused.
live, test, both Response
The endpoint, and the signing secret — for the only time.
The endpoint and its 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