---
title: "Rotate the webhook signing secret"
method: POST
path: "/api/v2/webhook/{id}/rotate-secret"
tags: ["webhook"]
---

# Rotate the webhook signing secret

`POST /api/v2/webhook/{id}/rotate-secret`

## Request

- Base URL: `https://central.zerotier.com`
- URL: `https://central.zerotier.com/api/v2/webhook/{id}/rotate-secret`
- Auth: HTTP bearer

Generates a new signing secret and places the previous secret into a grace/overlap window. The response contains exactly two active secrets: the new primary (expiryAt null) and the previous primary (expiryAt set to now + overlapHours).
If an overlap secret is already active (a previous rotation is still within its grace window), rotation is blocked and a 409 Conflict is returned. The caller must first explicitly revoke the overlap secret via DELETE /webhook-secret/{id}, or wait for the grace window to expire, before rotating again. This ensures the active secret count never exceeds two and makes the invariant explicit rather than silently evicting secrets.

## Path parameters

- `id` string, required

## Request body

- RotateWebhookSecretRequest
  - `overlapHours` integer: How many hours the previous secret remains valid after rotation. Defaults to 24. Use 0 for an immediate hard cutover with no overlap.

## Response `200`

Webhook with the new and previous secrets

- WebhookResponse
  - `id` string, required
  - `orgId` string, required
  - `description` string
  - `url` string, uri, required: The HTTPS endpoint URL that will receive webhook events. Must be a fully-qualified domain name (FQDN) — raw IP addresses are not allowed. The domain must not resolve to private or internal IP ranges (RFC1918, loopback, link-local, etc.).
  - `eventList` string[], required: Event types that trigger this webhook
  - `secrets` WebhookSecret[], required: Active secrets for this webhook. Normally contains one entry (the primary). During a rotation overlap window there will be two: the new primary (expiryAt null) and the previous primary (expiryAt set).
    - `id` string, required
    - `webhookId` string, required
    - `value` string, required: The HMAC-SHA256 signing secret value
    - `createdAt` string, date-time, required
    - `lastModified` string, date-time, required
    - `expiryAt` string, date-time, nullable: When set, the secret is in a grace/overlap window and will stop being valid after this time. Null means this is the active primary secret.
  - `createdAt` string, date-time, required
  - `lastModified` string, date-time, required

## Other responses

- `400`: Invalid data provided
- `401`: Missing or invalid authentication token
- `403`: Insufficient permissions
- `409`: An overlap secret is already active. Revoke it first via DELETE /webhook-secret/{id} or wait for its grace window to expire.
- `413`: Request body exceeds the 1 MB size limit
- `500`: Internal server error

---

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