Webhooks

$envless->webhooks->update()

Change an endpoint URL, events or enabled state

php
/**
 * @param WebhookPatch $patch
 * @return WebhookResource
 */
public function update(
    string $id,
    array $patch,
    int|float|null $timeout = null,
): array

Patches the name, URL, description, subscription set or enabled flag. At least one of those keys must be present: an empty array 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 $envless->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

php
use Envless\Envless;

$envless = new Envless();

$endpointId = '0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90';
$updated = $envless->webhooks->update($endpointId, [
    'eventTypes' => [
        'variable.created',
        'variable.updated',
        'variable_version.created',
    ],
    'enabled' => true,
]);

echo implode(', ', $updated['eventTypes']), PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$idstringYesEndpoint id, ids only and no slug form.
$patchWebhookPatchYesThe fields below, as one array.
$patch['url']stringNoReplacement https URL, re-validated against the full host ruleset.
$patch['eventTypes']list<string>NoComplete replacement subscription set, which must stay non empty.
$patch['name']stringNoReplacement label, at most 64 characters and never blank: an empty string is a 400, not a way to clear it.
$patch['description']string|nullNoReplacement note, at most 200 characters, or empty to clear it.
$patch['enabled']boolNoSet false to stop queuing new deliveries, must be a boolean.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

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 TypeScript

envless.webhooks.update()

The same method in @goenvless/sdk, with the same request, retries and errors.