---
title: "Rotate a Webhook signing secret"
method: POST
path: "/v1/webhooks/{id}/secret"
---

# Rotate a Webhook signing secret

`POST /v1/webhooks/{id}/secret`

## Request

- Base URL: `https://api.browserbase.com`
- URL: `https://api.browserbase.com/v1/webhooks/{id}/secret`
- Auth: API key in header `X-BB-API-Key`

Issue a new signing secret for a webhook. By default the previous secret keeps verifying for 24 hours so a receiver can be updated without dropping deliveries; pass `revokeImmediately` to end that window at once. The new secret is returned only here.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `revokeImmediately` boolean: Expire the old secret at once instead of honouring it for 24 hours. Use when responding to a leak; deliveries signed with the old secret stop verifying immediately.

## Response `200`

The new signing secret.

- object: The new signing secret. Shown once; store it now.
  - `secret` string, required: The new signing secret, prefixed `whsec_`.

## Other responses

- `429`: Too many previous secrets are still inside their grace window. Wait for one to expire, or retry with `revokeImmediately`.

## Changes

- **2026-10-16** `266d5199a560`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/browserbase/apis/browserbase-api/changes/v1/webhooks/:id/secret/post.md)

---

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