---
title: "Rotate the webhook signing secret"
method: POST
path: "/v1/workspaces/{workspace_id}/webhook-secret/rotate"
tags: ["Webhooks"]
---

# Rotate the webhook signing secret

`POST /v1/workspaces/{workspace_id}/webhook-secret/rotate`

## Request

- Base URL: `https://api.app.layer.ai/api`
- URL: `https://api.app.layer.ai/api/v1/workspaces/{workspace_id}/webhook-secret/rotate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.app.layer.ai/authorize`, token URL `https://auth.app.layer.ai/oauth/token`)
  - OAuth 2 (client credentials, token URL `https://api.app.layer.ai/api/oauth/token`, scopes: `workspace:write`)

Issue a new signing secret and put the outgoing one into a grace window. Both sign every delivery until the window closes, so update your receiver at your own pace rather than at the instant of rotation.

## Path parameters

- `workspace_id` string, uuid, required: Id of the workspace that owns the resource.

## Headers

- `Idempotency-Key` string

## Response `200`

Successful Response

- RotateWebhookSecretResponse
  - `secret` string, required: The new signing secret. Start verifying with it.
  - `previous_secret_expires_at` string, date-time, required: When the previous secret stops signing. Until then both secrets sign every delivery, so a receiver can be updated without dropping anything.

## Other responses

- `401`: Unauthenticated — missing or invalid Bearer token.
- `403`: Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.
- `404`: Resource not found.
- `409`: The outcome of the request with this `Idempotency-Key` is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in `Retry-After`.
- `422`: Invalid input parameters, or an `Idempotency-Key` reused for a different request.
- `429`: Rate limited — retry after the number of seconds in `Retry-After`.
- `500`: Internal server error.

## Changes

- **2026-10-20** `326f3bcdabcc`: 7 info
  - added the required property `error_code` to the response with the `401` status
  - added the required property `error_code` to the response with the `403` status
  - added the required property `error_code` to the response with the `404` status
  - added the required property `error_code` to the response with the `409` status
  - …3 more
- **2026-10-11** `2d86d473cda6`: 2 info
  - the endpoint scheme security `serviceAccount` was added to the API
  - the security scope `workspace:write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-10** `9425712a1f7e`: 2 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - the endpoint scheme security `oauth2` was added to the API
- **2026-09-21** `0aa077697d76`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/layer/apis/layer-rest-api/changes/v1/workspaces/:workspace_id/webhook-secret/rotate/post.md)

---

[API](https://skmtc.dev/layer/apis/layer-rest-api.md) · [All operations](https://skmtc.dev/layer/apis/layer-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layer/apis/layer-rest-api/revisions/326f3bcdabcc?raw)