Create a Webhook
Registers a new outbound webhook for the project. The platform will POST JSON to url when matching events occur (see List Webhooks for behavior).
Request
POST /api/webhooks HTTP/1.1
Host: app.nomacms.com
Content-Type: application/json
project-id: <project-uuid>
Authorization: Bearer <api-token>
Accept: application/jsonRequires the admin ability on the token.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name (max 255 characters) |
description | string | No | Notes |
url | string | Yes | HTTPS URL (max 2048 characters). Must pass URL validation and safety checks: public host, no embedded credentials, resolvable to non-private addresses |
secret | string | No | Signing secret: minimum 6 characters if set (max 255). Used for X-Webhook-Signature |
events | string[] | Yes | At least one event; each value must be one of the allowed events below |
sources | string[] | Yes | At least one of cms, api |
payload | boolean | No | Include full content_entry in deliveries when the event supports it (default true if omitted) |
status | boolean | No | Enable the webhook (default true if omitted) |
collection_ids | number[] | No | Restrict to these collection database ids. Omit or empty array = all collections |
Allowed events
content.created, content.updated, content.published, content.unpublished, content.deleted, content.trashed, content.restored, auth.signup.success, auth.login.success, auth.logout.success, auth.logout_all.success, auth.email_verification.verified.
For content.deleted, deliveries include ids but not a full content_entry object. Other content lifecycle events can include content_entry when payload is true (see List Webhooks).
URL safety
The API rejects URLs that use disallowed schemes, include user:pass@host, or resolve to private, loopback, link-local, or reserved IP ranges. You will get 422 with a validation error on url.
Reserved collection slug
You cannot create a collection whose slug is webhooks (validation error on collection create), but that rule applies to collections, not this route.
Response (201)
JSON object for the new webhook — same fields as Get a Webhook. The secret is not echoed back.
Errors
| Status | When |
|---|---|
| 400 | Missing project-id or project cannot be resolved |
| 401 | Missing or invalid bearer token |
| 403 | Token does not have admin (or *) |
| 422 | Validation failed (unknown event, bad URL, secret too short, invalid collection_ids, and so on) |
| 429 | Rate limited |
Example
import { createClient } from "@nomacms/js-sdk"
const client = createClient({
projectId: process.env.NOMA_PROJECT_ID!,
apiKey: process.env.NOMA_API_KEY!,
})
const created = await client.webhooks.create({
name: "Rebuild site",
url: "https://example.com/api/revalidate",
secret: "please-use-a-long-random-secret",
events: ["content.published", "content.updated"],
sources: ["cms", "api"],
payload: true,
status: true,
})
console.log(created)import axios from "axios"
async function main() {
const { data } = await axios.post(
"https://app.nomacms.com/api/webhooks",
{
name: "Rebuild site",
url: "https://example.com/api/revalidate",
secret: "please-use-a-long-random-secret",
events: ["content.published", "content.updated"],
sources: ["cms", "api"],
},
{
headers: {
"Content-Type": "application/json",
"project-id": process.env.NOMA_PROJECT_ID!,
Authorization: `Bearer ${process.env.NOMA_API_KEY}`,
Accept: "application/json",
},
},
)
console.log(data)
}
void main()curl -sS -X POST "https://app.nomacms.com/api/webhooks" \
-H "Content-Type: application/json" \
-H "project-id: $NOMA_PROJECT_ID" \
-H "Authorization: Bearer $NOMA_API_KEY" \
-H "Accept: application/json" \
-d '{"name":"Rebuild site","url":"https://example.com/api/revalidate","secret":"please-use-a-long-random-secret","events":["content.published","content.updated"],"sources":["cms","api"]}'Related
- Update a Webhook — Replace settings (full body)
- Webhook Logs — Verify deliveries
- JavaScript SDK — Webhooks —
webhooks.create