Skip to main content

​
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. 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

1

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.
2

Choose the events

Tick from the catalog, or subscribe with * or a glob like record.*.
3

Copy the signing secret

Shown once, on creation. Nothing can retrieve it afterwards. Store it before closing the dialog.

​
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.

​
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, which is also how the in-app assistant does it.
The tool returns the signing secret in its result, once, exactly as the app does. See Authentication for scoping a key.
webhooks:manage is one of the scopes an embedded block 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.

​
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.
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); it does not create the subscription.

​
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.