Webhooks API
Internal Application API · Enterprise Edition
Webhook management is an internal SPA route (session-authenticated) — there is no public, key-gated management surface. Outbound webhook delivery is an Enterprise-Edition feature. To learn how to consume webhook events, see the Webhooks guide.
Studio supports outbound webhooks that notify external services when content events occur. Webhooks are project-scoped and managed through the enterprise bridge.
All webhook management endpoints are project-scoped:
/api/workspaces/:workspaceId/projects/:projectId/webhooks/...These are part of Studio's authenticated application API (session-based, used by the Studio SPA) — there is no public, key-gated webhook management surface.
Enterprise Feature
Webhook management requires the enterprise bridge (ee/) and the api.webhooks_outbound feature flag. Outbound webhooks are not available in the self-hosted Community Edition.
List Webhooks
GET /api/workspaces/:workspaceId/projects/:projectId/webhooksResponse
[
{
"id": "uuid",
"name": "Production Webhook",
"url": "https://api.example.com/hooks/contentrain",
"events": ["content.saved", "content.deleted", "form.submitted"],
"active": true,
"secret": "****a1b2",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
]Requires workspace owner or admin and the api.webhooks_outbound feature (403 webhook.upgrade_required). The list masks secret to **** plus its last four characters.
Create Webhook
POST /api/workspaces/:workspaceId/projects/:projectId/webhooksRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
url | string | Yes | Delivery URL (http or https; localhost, private network, link-local and cloud-metadata hosts are rejected with 400 webhook.url_required) |
events | string[] | Yes | Events to subscribe to |
Supported Events
| Event | Description |
|---|---|
content.saved | Content entry created or updated |
content.deleted | Content entry deleted |
model.saved | Model definition created or updated |
branch.merged | Content branch merged |
branch.rejected | Content branch rejected (deleted) |
cdn.build_complete | A CDN build finished |
media.uploaded | A media asset was uploaded |
form.submitted | Form submission received (plans with forms.webhook_notification) |
branch.changes_requested | A reviewer requested changes on a content branch |
comment.submitted | A public comment was submitted (plans with comments.webhook_notification) |
comment.approved | A comment was approved (plans with comments.webhook_notification) |
deploy.triggered | A deploy hook fired; data carries provider, reason, ok, status |
schedule.fired | A scheduled publish_at / expire_at boundary passed; data.boundaries lists the entries |
The create and update routes do not check events against this list: an event name that is never emitted simply never matches. A subscription containing * receives every event.
Response
{
"id": "uuid",
"name": "Production Webhook",
"url": "https://api.example.com/hooks/contentrain",
"events": ["content.saved"],
"secret": "9f2c...64 hex characters",
"active": true
}Requires workspace owner or admin. Errors: 400 webhook.name_required, webhook.url_required, webhook.events_required; 403 webhook.upgrade_required (plan lacks api.webhooks_outbound); 403 webhook.limit_reached when the project already has the plan's maximum number of webhooks.
WARNING
The full secret (32 random bytes, hex-encoded) is only returned once at creation time; later reads return it masked. Use it to verify webhook payloads via HMAC-SHA256.
Update Webhook
PATCH /api/workspaces/:workspaceId/projects/:projectId/webhooks/:webhookId| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New display name |
url | string | No | New delivery URL |
events | string[] | No | New event subscriptions |
active | boolean | No | Enable/disable |
Requires workspace owner or admin. 400 when no field is given, 404 webhook.not_found. The same URL rules as create apply. Returns the updated webhook.
Delete Webhook
DELETE /api/workspaces/:workspaceId/projects/:projectId/webhooks/:webhookIdRequires workspace owner or admin. Returns { "deleted": true }.
Test Webhook
Send a test payload to verify connectivity.
POST /api/workspaces/:workspaceId/projects/:projectId/webhooks/:webhookId/testSends a signed ping event (header X-Contentrain-Event: ping) to the webhook URL with a 10-second timeout. Limited to 5 requests per minute per webhook (429). Requires workspace owner or admin.
{ "success": true, "statusCode": 200, "responseBody": "ok" }responseBody is truncated to 1000 characters. If the request fails or times out, the response is { "success": false, "statusCode": null, "responseBody": null, "error": "..." }.
List Deliveries
Get delivery history for a webhook.
GET /api/workspaces/:workspaceId/projects/:projectId/webhooks/:webhookId/deliveries| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 50 | Items per page (max 100) |
Requires workspace owner or admin.
Response
{
"deliveries": [
{
"id": "uuid",
"event": "content.saved",
"status": "delivered",
"response_code": 200,
"response_body": "ok",
"retry_count": 0,
"delivered_at": "2026-01-15T12:00:01Z",
"next_retry_at": null,
"created_at": "2026-01-15T12:00:00Z"
}
],
"total": 25,
"page": 1,
"limit": 50
}Delivery Statuses
| Status | Description |
|---|---|
pending | Awaiting delivery, or scheduled for a retry (next_retry_at is set) |
delivered | Successfully delivered (2xx response) |
failed | Gave up after the final retry, or the webhook was disabled or removed |
Retries
A non-2xx response or a timeout (10 seconds) leaves the delivery pending and schedules a retry with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, then 12 hours (at most 5 retries). After that the delivery is marked failed and workspace admins get an alert email (at most one per hour per webhook).
Plan Limits
| Plan | Webhook Endpoints |
|---|---|
| Starter | 3 |
| Pro | 25 |
| Enterprise | Unlimited |
Webhook Payload Format
{
"event": "content.saved",
"projectId": "uuid",
"timestamp": "2026-01-15T12:00:00.000Z",
"data": {
"models": ["blog-post"],
"locale": "en",
"source": "api"
}
}The top-level envelope is always { event, projectId, timestamp, data }. The data object is event-specific (see Webhooks guide).
Signature Verification
Webhook requests are POST with Content-Type: application/json, a User-Agent of Contentrain-Webhook/1.0, an X-Contentrain-Event header with the event name, and an X-Contentrain-Signature header containing the hex HMAC-SHA256 of the raw request body, keyed with the webhook secret:
import { createHmac } from 'crypto'
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expected = createHmac('sha256', secret).update(payload).digest('hex')
return signature === expected
}Related Pages
- Enterprise Edition -- webhook implementation details
- Chat API -- webhook events from agent operations