---
title: "Rotate a Webhook Signing Secret"
method: POST
path: "/v1/webhooks/subscriptions/{subscription_id}/rotate-secret"
tags: ["Webhooks"]
---

# Rotate a Webhook Signing Secret

`POST /v1/webhooks/subscriptions/{subscription_id}/rotate-secret`

## Request

- Base URL: `https://api.monaco.com`
- URL: `https://api.monaco.com/v1/webhooks/subscriptions/{subscription_id}/rotate-secret`
- Auth: none declared

Replaces the signing secret and returns the new one once. The old secret stops working immediately, and a delivery already in flight was signed with it, so accept both signatures on the receiver until traffic has settled.

**Error codes**

| `error.code` | HTTP | Cause | What to do |
| --- | --- | --- | --- |
| `not_found` | 422 | No subscription with this id exists in the calling org. | Check the id; a deleted subscription is never returned. |

## Path parameters

- `subscription_id` string, uuid, required

## Response `200`

Successful Response

- PublicItemResponseWebhookSecretRotateResponse
  - `data` WebhookSecretRotateResponse, required
    - `id` string, uuid, required: The subscription whose secret was replaced
    - `secret` string, required: The new signing secret, returned only here. The previous secret stops working immediately.
  - `meta` ResponseMeta
    - `timestamp` string, date-time: Server timestamp of the response

## Other responses

- `4XX`: Client error

## Changes

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

[Operation history](https://skmtc.dev/monaco/apis/monaco-public-api/changes/v1/webhooks/subscriptions/:subscription_id/rotate-secret/post.md)

---

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