---
title: "Rotate a webhook endpoint's signing secret"
method: POST
path: "/api/webhooks/{id}/rotate-secret"
tags: ["Webhooks"]
---

# Rotate a webhook endpoint's signing secret

`POST /api/webhooks/{id}/rotate-secret`

## Request

- Base URL: `https://api.wondercal.com`
- URL: `https://api.wondercal.com/api/webhooks/{id}/rotate-secret`
- Auth: HTTP bearer

Generates a new signing secret, returned once. Every delivery attempt made after rotation — including retries of events that were first attempted before rotation — is signed with both the new secret and the previous secret for WEBHOOK_SECRET_ROTATION_GRACE_MS (24 hours) after rotation. The X-WonderCal-Signature header carries one v1= entry per active secret during this window (for example: X-WonderCal-Signature: v1=<hex1>,v1=<hex2>) — verify against any entry that matches; you do not need to update your verification secret at the exact moment of rotation. After the grace window elapses, only the new secret is used to sign deliveries and the header reverts to a single v1= entry.

## Path parameters

- `id` string, required

## Response `200`

Secret rotated

- object
  - `data` WebhookSecretRotated
    - `secretKey` string: New plaintext signing secret. Shown once; store securely.

## Other responses

- `401`: Not authenticated
- `404`: Endpoint not found or not owned by user
- `429`: Rate limit exceeded. The Retry-After header indicates how many seconds to wait before retrying.

---

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