> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing subscriptions

> Create, inspect, rotate and delete webhook endpoints, from the app or from an MCP client.

## In the app

Open **Settings → Developers → Webhooks**. The list shows every endpoint in
the workspace: its URL, the events it subscribes to, its status, and when it was
created.

| Action                             | Who can do it        |
| ---------------------------------- | -------------------- |
| View the list and the delivery log | Any workspace member |
| Add an endpoint                    | Workspace **admin**  |
| Rotate a signing secret            | Workspace **admin**  |
| Delete an endpoint                 | Workspace **admin**  |

A subscription is a standing instruction that ships this workspace's data to a
third-party URL for as long as it exists, so creating one is workspace
configuration rather than day-to-day work. It sits at the same bar as minting an
API key.

### Adding one

<Steps>
  <Step title="Enter the URL">
    A public `http` or `https` endpoint. Custral refuses localhost and private
    addresses, and tells you which rule it hit. See
    [What Custral will and will not call](/dev/webhooks/security#what-custral-will-and-will-not-call).
  </Step>

  <Step title="Choose the events">
    Tick from the [catalog](/dev/webhooks/events/overview), or subscribe with
    `*` or a glob like `record.*`.
  </Step>

  <Step title="Copy the signing secret">
    Shown **once**, on creation. Nothing can retrieve it afterwards. Store it
    before closing the dialog.
  </Step>
</Steps>

### Rotating a secret

Rotate mints a new `whsec_…` and shows it once. It takes effect immediately with
no overlap window, so deploy the new value first. See
[Rotating](/dev/webhooks/security#rotating).

### Deleting

Deletion is immediate: matching events stop being queued for that endpoint. A
delivery already in flight finishes or fails on its own, and the endpoint's
delivery log goes with it.

## From an MCP client or the assistant

A key holding the `webhooks:manage` scope can register endpoints over
[MCP](/dev/mcp/overview), which is also how the in-app assistant does it.

| Tool                      | Scope                                   |
| ------------------------- | --------------------------------------- |
| `create_webhook_endpoint` | `webhooks:manage`                       |
| `list_webhook_endpoints`  | Read tier, available on the MCP surface |

```
Register a webhook at https://api.example.com/hooks/custral
for record.created and record.updated.
```

The tool returns the signing secret in its result, once, exactly as the app
does. See [Authentication](/dev/auth/overview) for scoping a key.

<Warning>
  `webhooks:manage` is one of the scopes an
  [embedded block](/dev/embeds/overview) can never be granted. A framed
  third-party page that could register a webhook could quietly forward a
  workspace's records to a URL of its choosing, so it is excluded from the
  grantable set rather than left to a review to catch.
</Warning>

## There is no `/v1` endpoint for this yet

Webhook management is **not** part of the public `/v1` REST surface. The routes
the app itself uses are session-authenticated rather than API-key
authenticated, so an `sk_…` key cannot call them.

To manage subscriptions programmatically today, use the MCP tools above. If a
plain REST endpoint would suit your integration better, say so at
[hello@custral.com](mailto:hello@custral.com).

<Note>
  This is the one part of the developer platform where the SDK is a **receiver
  only**. `@custral/sdk` verifies and dispatches inbound deliveries
  ([`custral.webhooks`](/dev/sdks/typescript)); it does not create the
  subscription.
</Note>

## Reading the delivery log

Open an endpoint to see its last 100 deliveries, newest first, with the status
your server returned on each. The fields are described under
[The delivery log](/dev/webhooks/delivery#the-delivery-log).


## Related topics

- [Delivery and retries](/dev/webhooks/delivery.md)
- [Quickstart](/dev/webhooks/quickstart.md)
- [Events](/dev/events.md)
- [Sequences](/automation/sequences/overview.md)
- [Getting Started](/team/getting-started.md)