# Rotate the signing secret

Source: https://docs.coderhelm.com/api/reference/webhook-endpoints/rotate-webhook-secret

`POST /api/webhooks/endpoints/{endpoint_id}/secret/rotate`

Makes a new secret. For `overlap_hours` (24 unless set) every request carries two signatures, one per secret, so a receiver verifying with either keeps working while you update it. Then only the new secret signs.

## Authentication

A team API key: `Authorization: Bearer chk_...`. The key needs the `webhooks` scope. See [Authentication](https://docs.coderhelm.com/api/authentication).

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `endpoint_id` | string | yes | The endpoint's id. |

## Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `overlap_hours` | integer or null | no | Hours the old secret keeps signing beside the new one: 0 to 168. Defaults to 24. With 0 the old secret stops at once. |

## Responses

### 200

The new secret, shown once here.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `previous_secret_expires_at` | string or null | no | Until then, requests carry a second signature made with the old one. |
| `secret` | string | yes | The new secret. Requests are signed with it from now on. |

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### 400

`overlap_hours` is outside 0 to 168.

### 401

The key is missing, malformed, revoked or expired, or the person who made it left the team.

### 403

The key lacks the scope this endpoint needs (`missing_scope`).

### 404

No such endpoint on this team.

### 429

Over the key's rate limit (`rate_limited`), or, for endpoints that start work, over the team's monthly token limit (`token_limit_reached`).

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After`.

### 500

Something failed on CoderHelm's side. Safe to retry reads.

## Example request

cURL:

```bash
curl -X POST 'https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8/secret/rotate' \
  -H "Authorization: Bearer $CODERHELM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "overlap_hours": 24
}'
```

TypeScript:

```ts
const res = await fetch("https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8/secret/rotate", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CODERHELM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "overlap_hours": 24
    }),
});
if (!res.ok) {
  const { error, code } = await res.json();
  throw new Error(`${res.status} ${code}: ${error}`);
}
const data = await res.json();
```

Python:

```python
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CODERHELM_API_KEY']}",
}
body = {
    "overlap_hours": 24,
}
res = requests.request("POST", "https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8/secret/rotate", headers=headers, json=body)
if not res.ok:
    raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")
data = res.json()
```

## Example response

```json
{
  "previous_secret_expires_at": "2026-10-27T09:00:00Z",
  "secret": "whsec_k0q8vX2mZp5Rr3t1YbN6cH9dLwE4fJ7aS1uG0iT2oQs="
}
```