Skip to content

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/webhooks

Response ​

json
[
  {
    "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/webhooks

Request Body ​

FieldTypeRequiredDescription
namestringYesDisplay name
urlstringYesDelivery URL (http or https; localhost, private network, link-local and cloud-metadata hosts are rejected with 400 webhook.url_required)
eventsstring[]YesEvents to subscribe to

Supported Events ​

EventDescription
content.savedContent entry created or updated
content.deletedContent entry deleted
model.savedModel definition created or updated
branch.mergedContent branch merged
branch.rejectedContent branch rejected (deleted)
cdn.build_completeA CDN build finished
media.uploadedA media asset was uploaded
form.submittedForm submission received (plans with forms.webhook_notification)
branch.changes_requestedA reviewer requested changes on a content branch
comment.submittedA public comment was submitted (plans with comments.webhook_notification)
comment.approvedA comment was approved (plans with comments.webhook_notification)
deploy.triggeredA deploy hook fired; data carries provider, reason, ok, status
schedule.firedA 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 ​

json
{
  "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
FieldTypeRequiredDescription
namestringNoNew display name
urlstringNoNew delivery URL
eventsstring[]NoNew event subscriptions
activebooleanNoEnable/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/:webhookId

Requires workspace owner or admin. Returns { "deleted": true }.


Test Webhook ​

Send a test payload to verify connectivity.

POST /api/workspaces/:workspaceId/projects/:projectId/webhooks/:webhookId/test

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

json
{ "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
ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber50Items per page (max 100)

Requires workspace owner or admin.

Response ​

json
{
  "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 ​

StatusDescription
pendingAwaiting delivery, or scheduled for a retry (next_retry_at is set)
deliveredSuccessfully delivered (2xx response)
failedGave 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 ​

PlanWebhook Endpoints
Starter3
Pro25
EnterpriseUnlimited

Webhook Payload Format ​

json
{
  "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:

ts
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
}

Released under the AGPL-3.0 License. Privacy