Skip to main content
POST
Mint a new signing secret, keeping the old one alive briefly.

Authorizations

Authorization
string
header
required

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

webhookId
string<uuid>
required

The endpoint’s id, as returned when it was registered. An endpoint id.

Example:

"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.

id
string<uuid>
required

The endpoint’s id. A bare uuid.

url
string
required

Where deliveries are POSTed. https:// only, no credentials, and not a private or loopback address — deliveries are made from inside our network.

subscribed_events
enum<string>[]
required

What this endpoint hears about. Never empty. ⚠️ An unknown name is refused at registration rather than accepted and never delivered.

One event type.

Available options:
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
brand_id
string<uuid> | null
required

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.

environment
enum<string>
required

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.

Available options:
live,
test,
both
active
boolean
required

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.

consecutive_failures
integer
required

⚠️ 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.

last_success_at
string<date-time> | null
required

The last 2xx we received. Null if there has never been one.

last_failure_at
string<date-time> | null
required

The last delivery that used up its ladder.

disabled_at
string<date-time> | null
required

When delivery stopped. Null while active.

disabled_reason
string | null
required

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.

created_at
string<date-time>
required

ISO 8601, UTC.

secret
string
required

⚠️ 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.