# Rotate a webhook secret

> webhook_rotate_secret — New signing secret, returned ONCE.

Source: https://x.builera.app/docs/en/reference/webhook_rotate_secret

`webhook_rotate_secret` · Changes an X-Buddy setting

New signing secret, returned ONCE. For 24 hours both the new and the previous secret sign every delivery (two v1 signatures), so the receiver can switch without losing events.

| | |
|---|---|
| REST | `POST /api/public/v1/webhooks/{endpoint_id}/rotate-secret` |
| MCP tool | `webhook_rotate_secret` |
| Permission needed | `integrations.manage` — Owner, Manager |
| Scope group | `webhooks:manage` |
| Group | Events and webhooks |
| Shown up front in profiles | Infrastructure |

## Input {#input}

| Field | Type | Required | Description |
|---|---|---|---|
| `endpoint_id` | string (uuid) | Yes | Endpoint id. |

## Result {#output}

Returns the operation's result in the `{ data, meta }` envelope.

> [!IMPORTANT]
> Needs an idempotency key (`Idempotency-Key`, 8–128 characters). Retrying with the same key never repeats the action.

## Example {#example}

### Call over REST {#example-rest}

```bash
curl -X POST "https://reach-link-craft.lovable.app/api/public/v1/webhooks/00000000-0000-4000-8000-000000000001/rotate-secret" \
  -H "Authorization: Bearer $XBUDDY_API_KEY" \
  -H "Idempotency-Key: 6f1c2a90-example-key" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Call over MCP {#example-mcp}

```json
{
  "method": "tools/call",
  "params": {
    "name": "webhook_rotate_secret",
    "arguments": {
      "endpoint_id": "00000000-0000-4000-8000-000000000001",
      "idempotency_key": "6f1c2a90-example-key"
    }
  }
}
```

## Errors you may get {#errors}

| Code | HTTP | Retryable |
|---|---|---|
| [`unauthorized`](/docs/en/errors/unauthorized) | 401 | No |
| [`key_expired`](/docs/en/errors/key_expired) | 401 | No |
| [`integration_revoked`](/docs/en/errors/integration_revoked) | 401 | No |
| [`connection_not_linked`](/docs/en/errors/connection_not_linked) | 403 | No |
| [`integration_paused`](/docs/en/errors/integration_paused) | 403 | No |
| [`workspace_integrations_paused`](/docs/en/errors/workspace_integrations_paused) | 403 | No |
| [`integration_authorization_lost`](/docs/en/errors/integration_authorization_lost) | 403 | No |
| [`workspace_suspended`](/docs/en/errors/workspace_suspended) | 403 | No |
| [`forbidden`](/docs/en/errors/forbidden) | 403 | No |
| [`invalid_input`](/docs/en/errors/invalid_input) | 422 | No |
| [`rate_limited`](/docs/en/errors/rate_limited) | 429 | Yes |
| [`internal`](/docs/en/errors/internal) | 500 | Yes |
| [`read_only`](/docs/en/errors/read_only) | 403 | No |
| [`idempotency_key_required`](/docs/en/errors/idempotency_key_required) | 428 | No |
| [`idempotency_conflict`](/docs/en/errors/idempotency_conflict) | 409 | No |
| [`idempotency_processing`](/docs/en/errors/idempotency_processing) | 409 | Yes |
| [`conflict`](/docs/en/errors/conflict) | 409 | No |
| [`precondition_failed`](/docs/en/errors/precondition_failed) | 422 | No |
| [`not_found`](/docs/en/errors/not_found) | 404 | No |

[Back to all operations](/docs/en/reference)