Skip to main content
PATCH
Change the URL, the subscription, the brand filter or the active flag.

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"

Body

application/json

The properties to change. Anything omitted is left as it was.

The change.

url
string

A new delivery URL, on the same terms as registration.

Example:

"https://api.example.test/hooks/vumasign"

events
enum<string>[]

Replaces the whole subscription list. Not merged with it.

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

null removes the filter. Omitting the property leaves it unchanged.

environment
enum<string>

live, test or both. Replaces the setting. Deliveries already queued are not re-routed; the next event is.

Available options:
live,
test,
both
active
boolean

false stops delivery and KEEPS THE QUEUE — this is the operation to use for maintenance, not DELETE. true resumes it AND resets the health window, which is how an auto-disabled endpoint is brought back.

Response

The endpoint as it now stands, after every change was applied.

The endpoint.

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.