Webhooks
Webhooks let you receive real-time HTTP notifications when events occur in your project. Configure a webhook URL and select which events to listen for — Studio will POST a signed payload to your endpoint whenever a matching event fires.
Managed service / Enterprise Edition
Outbound webhooks are an Enterprise Edition feature, gated by the api.webhooks_outbound plan feature. They are available on Contentrain's managed service (Starter plans and above) and on self-hosted Enterprise Edition deployments. They are not available in the self-hosted Community Edition.
Creating a Webhook
- Open the project settings and go to the Webhooks tab
- Click Create Webhook
- Enter a Webhook Name and the Endpoint URL (
https://is recommended;http://is also accepted) - Select the Events you want to subscribe to
- A signing secret is generated automatically for signature verification. Copy it right away — it is shown only once, when the webhook is created
Only workspace owners and admins can view and manage webhooks.

WARNING
Webhook URLs must point to public endpoints. Studio blocks requests to private networks (RFC 1918), localhost, link-local addresses, and cloud metadata endpoints for SSRF protection.
Event Types
Studio supports thirteen webhook event types:
| Event | Fires When |
|---|---|
content.saved | A content entry is created or updated |
content.deleted | A content entry is deleted |
model.saved | A content model is created or updated |
branch.merged | A cr/* branch is merged into the contentrain content branch |
branch.rejected | A branch is rejected (deleted) |
branch.changes_requested | A reviewer requests changes on a review branch |
cdn.build_complete | A CDN build finishes, whether it succeeded or failed (check status). A build that finds nothing to publish does not fire |
media.uploaded | A media asset is uploaded |
form.submitted | A public form submission is received |
comment.submitted | A visitor submits a comment |
comment.approved | A comment is approved |
deploy.triggered | A deploy hook is triggered |
schedule.fired | A scheduled run fires |
Event Payload Format
All webhook payloads follow the same structure:
{
"event": "content.saved",
"projectId": "project-uuid",
"timestamp": "2026-04-02T10:30:00.000Z",
"data": {
"models": ["blog-posts"],
"locale": "en",
"source": "api"
}
}The envelope is always { event, projectId, timestamp, data }. The data field varies by event type and contains event-specific information. Most events include a source field (api, conversation, etc.) indicating how the change was made.
Event-Specific Data
content.saved:
{
"models": ["blog-posts"],
"locale": "en",
"source": "api"
}content.deleted:
{
"models": ["blog-posts"],
"locale": "en",
"locales": ["en"],
"entryIds": ["a1b2c3d4e5f6", "g7h8i9j0k1l2"],
"source": "conversation"
}locales lists every locale the delete touched. Deleting a dictionary key from the editor also fires this event.
model.saved:
{
"modelId": "blog-posts",
"source": "api"
}branch.merged:
{
"branch": "cr/content/blog-posts/en/1774800862-27c1",
"source": "api"
}branch.rejected: { "branch": "cr/...", "source": "api" }
branch.changes_requested:
{
"branch": "cr/content/blog-posts/en/1774800862-27c1",
"comment": "Please shorten the intro.",
"requestedBy": "user-uuid",
"source": "api"
}When a reviewer requests changes through the AI chat, requestedBy is omitted and source is conversation.
cdn.build_complete:
{
"buildId": "build-uuid",
"status": "success",
"filesUploaded": 15,
"durationMs": 3200,
"error": null
}On a failed build, status is "failed" and error holds the message.
media.uploaded:
{
"assetId": "asset-uuid",
"filename": "hero-banner.webp",
"contentType": "image/webp"
}form.submitted:
{
"submissionId": "submission-uuid",
"modelId": "contact-form",
"status": "pending"
}comment.submitted: commentId, modelId, entryId, locale, parentId, status
comment.approved: commentId, modelId, entryId, locale, source
deploy.triggered: provider, reason, ok, status
schedule.fired: boundaries, an array of { modelId, entryId, locale, kind, fireAt }
Webhook Security
HMAC-SHA256 Signatures
Every webhook delivery is a POST with Content-Type: application/json, a User-Agent of Contentrain-Webhook/1.0, an X-Contentrain-Event header carrying the event name, and a signature in the X-Contentrain-Signature header. The signature is an HMAC-SHA256 hash of the request body using your webhook secret.
To verify a webhook delivery:
import { createHmac, timingSafeEqual } from 'crypto'
function verifyWebhook(body, signature, secret) {
const expected = createHmac('sha256', secret)
.update(body)
.digest('hex')
return timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
)
}WARNING
Always verify webhook signatures before processing the payload. Use timing-safe comparison to prevent timing attacks.
SSRF Protection
Studio validates webhook URLs to prevent Server-Side Request Forgery:
- Blocked:
localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16,::1, cloud metadata endpoints - Required:
http://orhttps://protocol - Recommended: Use HTTPS in production (not enforced)
Test Delivery
You can send a test delivery to verify your webhook configuration:
- Open the webhook in settings
- Click Send Test
- Studio sends a test payload to your endpoint
- A toast reports the result: "Test event delivered successfully", or "Test delivery failed" with the status
Delivery Logs
Every webhook delivery is logged. The Studio UI does not list deliveries; read them with the API (owner/admin):
GET /api/workspaces/{workspaceId}/projects/{projectId}/webhooks/{webhookId}/deliveriesEach entry includes:
| Field | Description |
|---|---|
| Event type | Which event triggered the delivery |
| Status code | HTTP response code from your endpoint |
| Response time | How long the delivery took |
| Timestamp | When the delivery was attempted |
| Payload | The data that was sent |
Retry Behavior
If a webhook delivery fails (non-2xx response or timeout), Studio retries with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 12 hours |
After 5 failed retries, the delivery is marked as permanently failed, and the workspace owners and admins get an alert email (at most one per hour per webhook, when an email provider is configured). Failed deliveries remain in the delivery log.
TIP
Ensure your webhook endpoint responds quickly (under 10 seconds) with a 2xx status code. Return 200 OK as soon as you receive the payload, then process it asynchronously.
Managing Webhooks
Editing a Webhook
In the Studio UI you can Pause and Resume a webhook (its active status). To change its URL or events, use the update API (PATCH on the webhook) or delete the webhook and create a new one.
Deleting a Webhook
To remove a webhook:
- Open webhook settings
- Click the delete button on the webhook
- Confirm the deletion
Deleting a webhook stops all future deliveries immediately.
Plan Limits
| Feature | Free | Starter | Pro | Enterprise |
|---|---|---|---|---|
| Outbound webhooks | 0 | 3 | 25 | Unlimited |
Use Cases
| Scenario | Events | Action |
|---|---|---|
| Rebuild static site | branch.merged | Trigger CI/CD pipeline |
| Notify Slack on new content | content.saved | Post to Slack channel |
| Invalidate CDN cache | cdn.build_complete | Purge cache keys |
| Process form submissions | form.submitted | Send to CRM or email |
| Sync search index | content.saved, content.deleted | Update Algolia/Typesense |
| Audit trail | All events | Log to monitoring service |
Next Steps
- CDN — Deliver content through the built-in CDN
- Forms — Accept and manage form submissions
- Conversation API — Programmatic content management