POST /v1/webhook-endpoints/:endpointId/rotate-secret

Rotates the endpoint's signing secret. The previous secret remains valid until previousSecretExpiresAt so receivers can dual-verify during cutover without dropping deliveries. During the overlap window, X-Layers-Signature includes multiple v1=<mac> entries - one for each active secret - and your verifier should accept a match from any of them.

Example

curl -X POST https://api.layers.com/v1/webhook-endpoints/d4c71b62-.../rotate-secret \
  -H "Authorization: Bearer $LAYERS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "endpointId": "d4c71b62-7f08-4dc9-9d2c-8f7e2b9c4411",
  "signingSecret": "whsec_new...",
  "previousSecretExpiresAt": "2026-04-21T18:28:00.000Z",
  "warning": "Signing secret shown once. The previous secret remains valid during the overlap window - dual-verify both in your handler during cutover."
}

Cutover pattern

1. Call rotate. Store the new signingSecret under a different key from your current one - e.g., LAYERS_WEBHOOK_SECRET_NEW + LAYERS_WEBHOOK_SECRET.
2. Update your verifier to accept a signature from EITHER secret.
3. Deploy. Watch for deliveries signed with both MACs.
4. After the overlap window ends, drop the old secret from your config.

Errors