---
title: "Rotate a webhook endpoint's signing secret"
method: POST
path: "/webhooks/endpoints/{endpoint_id}:rotateSecret"
tags: ["Webhooks"]
---

# Rotate a webhook endpoint's signing secret

`POST /webhooks/endpoints/{endpoint_id}:rotateSecret`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/webhooks/endpoints/{endpoint_id}:rotateSecret`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/webhooks/endpoints/:endpoint_id:rotateSecret/post.ts> (a function with typed inputs; its response is checked against the schema)

Issues a new signing secret for the endpoint, returned exactly once. With mode graceful (the default) the previous secret keeps verifying for 24 hours (previous_secret_invalid_at in the response) so the new secret can be rolled out across a deploy without dropping deliveries in flight. With mode immediate the previous secret stops verifying at once, for a secret that may be compromised. A missing or wrong-organization id returns 404.

## Path parameters

- `endpoint_id` string, required: Endpoint identifier.

## Request body

- WebhookRotateSecretRequest: Optional body for rotating a signing secret: how the previous secret is retired.
  - `mode` 'graceful' | 'immediate': graceful: the previous secret keeps verifying for 24 hours so the new one can be rolled out across a deploy. immediate: the previous secret stops verifying at once, for a secret that may be compromised. Omit for graceful.

## Response `200`

OK

- WebhookRotateSecretResponse: A rotated signing secret, shown once, with the grace window during which the old secret still verifies.
  - `id` string, required: Endpoint identifier.
  - `previous_secret_invalid_at` string, date-time: When the previous signing secret stops verifying: 24 hours out for a graceful rotation, already past for an immediate one. Until then both the old and new secret verify.
  - `secret` string, required: New Standard Webhooks signing secret (whsec_...). Shown once and never returned again.

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-17** `f732df58a578`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/webhooks/endpoints/:endpoint_id:rotateSecret/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)