---
title: "Rotate the signing secret"
method: POST
path: "/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret"
tags: ["Webhooks"]
---

# Rotate the signing secret

`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Issues a new signing secret for the same endpoint and returns it — the second and last time a secret is ever returned. This is the `…:rotate-secret` action; the path segment is `{webhook_id}:rotate-secret`.
The change takes effect on the next delivery, including retries of deliveries already queued, so roll the new secret out to your receiver promptly. There is no overlap window in which both secrets verify.

## Response `200`

A new signing secret was issued.

- WebhookWithSecret
  - `id` string, required: Public webhook ID (whk_ prefix).
  - `project_id` string, required
  - `url` string, uri, required: Where deliveries are POSTed.
  - `events` string[], required: Which events this endpoint receives. Each entry is an exact type (`generation.completed`), a resource wildcard (`generation.*`), or `*` for everything. A bare resource name (`generation`) matches nothing and is rejected.
  - `description` string, nullable, required: Operator-facing label.
  - `active` boolean, required: Whether deliveries are attempted.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `secret` string, required: The signing key, returned only by create and rotate. A generated one carries the `whsec_` prefix; a chosen one is returned as sent. Never readable afterwards.

## Other responses

- `401`: Missing or invalid credentials.
- `404`: The resource does not exist (existence is not leaked).
- `501`: The requested path is not enabled on this deployment — a webhook secret cannot be stored where no credential-sealing key is configured.

---

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