Webhooks

envless.webhooks.update()

Change an endpoint URL, events or enabled state

ts
update(id: string, patch: WebhookPatch, options?: RequestScope): Promise<WebhookResource>

Patches the name, URL, description, subscription set or enabled flag. At least one of those keys must be present: an empty object is a 400, not a no-op. url is re-validated against the full https and public host ruleset on every change, and passing null or an empty string for description clears the note.

eventTypes replaces the subscription set wholesale, unlike scopes on keys.update, which merges. Send the complete list you want rather than a delta. It must stay non empty, so there is no way to subscribe to nothing: disable the endpoint instead.

Disabling does not drain the queue. Deliveries already queued are not cancelled, the worker picks them up, sees the endpoint is disabled and marks them failed with Endpoint disabled, so expect a burst of failures in the log right after you turn it off. Nothing new is queued while enabled is false, and events that occur during the downtime are lost to this endpoint rather than buffered.

Example

ts
const updated = await envless.webhooks.update('0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90', {
    eventTypes: ['variable.created', 'variable.updated', 'variable_version.created'],
    enabled: true
})

console.log(updated.eventTypes)

Parameters

ParameterTypeRequiredDescription
idstringYesEndpoint id, ids only and no slug form.
patch.urlstringNoReplacement https URL, re-validated against the full host ruleset.
patch.eventTypesArray<string>NoComplete replacement subscription set, which must stay non empty.
patch.namestringNoReplacement label, at most 64 characters and never blank: an empty string is a 400, not a way to clear it.
patch.descriptionstringNoReplacement note, at most 200 characters, or empty to clear it.
patch.enabledbooleanNoSet false to stop queuing new deliveries, must be a boolean.
options.signalAbortSignalNoCancels the request.

Returns

WebhookResource reflecting the saved endpoint, still with secretLastFour in place of any secret.

Worth knowing

  • The signing secret is untouched by this route, use rotateSecret to change it.
  • Read the current eventTypes first if you mean to add one, since a partial list silently unsubscribes the rest.

Required scopes

webhooks:write

Underlying endpoint

PATCH /webhooks/{id}

Request and response schema, every error code, and a live playground.

In Python

envless.webhooks.update()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.webhooks.update

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->webhooks->update()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.