rotateSecret(id: string, options?: RequestScope): Promise<RotatedSecretResource>Generates a new signing secret for the endpoint and resolves with it. This is the only route that can hand you a usable secret after create, and the resolved 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
const rotated = await envless.webhooks.rotateSecret('0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90')
console.log(rotated.secret)
console.log(rotated.secretLastFour, rotated.secretRolledAt)Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Endpoint id, ids only and no slug form. |
options.signal | AbortSignal | No | Cancels the request. |
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 toverifyWebhookSignature. - Emits
webhook.secret_rotated, which carriessecretLastFourandsecretRolledAtbut 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 Python
envless.webhooks.rotate_secret()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.webhooks.rotate_secret
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->webhooks->rotateSecret()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.