def rotate_secret(
id: str,
*,
timeout: float | None = None,
) -> RotatedSecretResourceasync def rotate_secret(
id: str,
*,
timeout: float | None = None,
) -> RotatedSecretResourceGenerates 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
from envless import envless
rotated = envless.webhooks.rotate_secret(
'0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90'
)
print(rotated['secret'])
print(rotated['secretLastFour'], rotated['secretRolledAt'])import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
rotated = await envless.webhooks.rotate_secret(
'0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90'
)
print(rotated['secret'])
print(rotated['secretLastFour'], rotated['secretRolledAt'])
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | Yes | Endpoint id, ids only and no slug form. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. 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 toverify_webhook_signature. - 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 TypeScript
envless.webhooks.rotateSecret()
The same method in @goenvless/sdk, with the same request, retries and errors.