---
title: "Rotate a webhook endpoint secret"
method: POST
path: "/v4/webhook_endpoints/{id}/rotate_secret"
tags: ["Webhooks"]
---

# Rotate a webhook endpoint secret

`POST /v4/webhook_endpoints/{id}/rotate_secret`

## Request

- Base URL: `https://api.kit.com`
- URL: `https://api.kit.com/v4/webhook_endpoints/{id}/rotate_secret`
- Auth: one of:
  - API key in header `X-Kit-Api-Key`
  - OAuth 2
    - Authorization code: `https://api.kit.com/v4/oauth/authorize`
    - Token URL: `https://api.kit.com/v4/oauth/token`

Generates a new signing secret for the endpoint and returns it. **The response is the only time the new `secret` appears in plaintext** — store it securely.

To avoid dropping deliveries mid-rollout, the previous secret keeps verifying until the overlap window closes (the endpoint's `previous_secret_expires_at`). During the window every delivery is signed with both secrets, so the `X-Kit-Signature` header carries two `v1` entries — see [secret rotation](/webhooks/verifying-signatures#secret-rotation).

Rotating again while a previous rotation's window is still open returns `409`; pass `force: true` to rotate anyway and immediately expire the older secret. Once you've switched over, you can close the window early with [Revoke the previous secret](/api-reference/webhooks/revoke-the-previous-webhook-endpoint-secret).

## Path parameters

- `id` integer, required

## Request body

- object
  - `force` boolean: Rotating again while a previous rotation's overlap window is still open returns `409` (see the responses below). Pass `true` to rotate anyway, immediately expiring the older secret.

## Response `200`

Rotates the secret and returns the new one

- object
  - `webhook_endpoint` object, required
    - `id` integer, required
    - `name` string, required
    - `url` string, required
    - `events` string[], required
    - `status` string, required
    - `source` string, required
    - `description` string, required
    - `created_by_app` unknown, required
    - `created_at` string, required
    - `previous_secret_expires_at` string, required
    - `secret` string, required: The new signing secret (`whsec_` prefix). **Returned only in this response** — store it securely. The previous secret keeps verifying deliveries until `previous_secret_expires_at`.

## Other responses

- `404`: Returns a 404 when the provided id does not exist
- `409`: Returns 409 when the previous rotation's overlap window is still open

## Changes

- **2026-11-03** `f04308f83b63`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kit/apis/kit-api/changes/v4/webhook_endpoints/:id/rotate_secret/post.md)

---

[API](https://skmtc.dev/kit/apis/kit-api.md) - [All operations](https://skmtc.dev/kit/apis/kit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kit/apis/kit-api/revisions/f04308f83b63?raw)