---
title: "Rotate a webhook connection's signing secret"
method: POST
path: "/v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate"
tags: ["Webhook Connections", "tier:standard"]
---

# Rotate a webhook connection's signing secret

`POST /v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Generates a new signing secret for the connection and returns it once. The previous secret stops validating immediately, so update the receiver before rotating in production. Send an Idempotency-Key to retry safely: a retry under the same key returns the same new secret instead of rotating again.

## Path parameters

- `projectId` string, required: Project ID (base62-encoded).
- `id` string, required: Webhook connection ID (base62-encoded).

## Headers

- `Idempotency-Key` string

## Response `200`

OK

- WebhookConnectionCreated
  - `created_at` string, date-time, required
  - `created_by` Creator
    - `id` string, required: Creator's user ID
    - `name` string, required: Creator's display name
  - `id` string, required
  - `name` string: Optional human label for the connection.
  - `project_id` string, required
  - `revoked_at` string, date-time: Set when the connection was deleted/revoked; absent for active connections. A revoked connection stops delivering and is skipped by alerts that still reference it.
  - `secret` string, required: Signing secret — shown only at create/rotate time. Store it securely; it cannot be retrieved again. Used to verify the X-Webhook-Signature header on delivered payloads.
  - `secret_prefix` string, required: Masked signing-secret prefix for identification. The full secret is shown only at create/rotate time and cannot be retrieved afterward.
  - `surface` 'PLATFORM' | 'RADAR', required: Which Particle surface created this connection. Fixed at create time and inferred from the caller's authenticated surface context. Provenance only — an alert on either surface can deliver through it. Render it to show where the endpoint was registered.
  - `url` string, required: Destination URL that signed POSTs are delivered to.

## Other responses

- `default`: Error

---

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