---
title: "Webhooks API"
description: "Subscriptions, signing secrets and delivery."
label: "Webhooks"
generated: "the API catalogue in apps/control-plane/src/routes/developer.ts"
---


Deliveries are signed with a per-subscription secret you can rotate. Treat a webhook as a notification, never as an authorization: verify the signature and then read state back from the API.

## Endpoints

| | Endpoint | Permission | Notes |
| --- | --- | --- | --- |
| `GET` | `/v1/webhooks` | `webhook:read` | — |
| `POST` | `/v1/webhooks` | `webhook:manage` | — |
| `POST` | `/v1/webhooks/{subscriptionId}/rotate-secret` | `webhook:manage` | — |

## What each endpoint does

### `GET /v1/webhooks`

List webhook subscriptions.

Requires `webhook:read`.

### `POST /v1/webhooks`

Create a webhook subscription.

Requires `webhook:manage`.

### `POST /v1/webhooks/{subscriptionId}/rotate-secret`

Rotate the signing secret.

Requires `webhook:manage`.