Webhooks

$envless->webhooks->rotateSecret()

Issue a new signing secret for an endpoint

php
/** @return RotatedSecretResource */
public function rotateSecret(
    string $id,
    int|float|null $timeout = null,
): array

Generates a new signing secret for the endpoint and returns it. This is the only route that can hand you a usable secret after create, and the returned secret is again returned exactly once: reads only ever give secretLastFour, so losing it means rotating again.

There is no dual secret grace window. The old secret stops verifying the instant the call commits, so deliveries already in flight were signed with the old one and will fail at your receiver, and any retry of an earlier failure is re-signed with the new one. Expect a short window of rejected requests.

The safe sequence is to deploy a receiver that accepts both the current secret and a new one read from config, call this, write the returned secret to config, then drop the old value once lastSuccessAt starts advancing again. If you cannot do that, rotate during a quiet period and plan for the failures.

Example

php
use Envless\Envless;

$envless = new Envless();

$endpointId = '0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90';
$rotated = $envless->webhooks->rotateSecret($endpointId);

echo $rotated['secret'], PHP_EOL;
echo "{$rotated['secretLastFour']} {$rotated['secretRolledAt']}", PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$idstringYesEndpoint id, ids only and no slug form.
$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

RotatedSecretResource with the new secret, its secretLastFour and the secretRolledAt timestamp.

Worth knowing

  • There is no request body and the success status is 200, not 201, because nothing new is created.
  • Pass the full secret including the ev_whsec_ prefix to Envless::verifyWebhookSignature().
  • Emits webhook.secret_rotated, which carries secretLastFour and secretRolledAt but never the secret.

Required scopes

webhooks:write

Underlying endpoint

POST /webhooks/{id}/rotate

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

In TypeScript

envless.webhooks.rotateSecret()

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