Skip to content

Webhooks

A webhook is an HTTP POST that Plenary sends to a URL you choose when something happens to an entry: it is created, updated, published, unpublished, or deleted, or a visitor submits a form. Use webhooks to revalidate a statically built site, reindex search, notify a chat channel, or push form entries into a CRM.

Webhooks fire after the change is saved and cannot alter or block it. To change data while it is being saved, use a transformer instead.

You attach a webhook to one of three things. Each fires for a different set of entries:

Attached to Fires for Events it can subscribe to Configured in
A content model Entries of that model entry.created, entry.updated, entry.published, entry.unpublished, entry.deleted The model’s Webhooks tab
A form Form entries of that form form.submitted The form’s Webhooks tab
A site Entries of every model and every form on that site All six The site’s Webhooks tab under Site Management

When an entry’s model has a webhook and its site also has one subscribed to the same event, both fire, as separate deliveries.

Site webhooks differ in three ways: they can send All fields or No field data but not Selected fields (they span models, so there is no single field list), so they never carry a private field; changes to them are not recorded in revision history; and they need a content:webhooks:manage grant that covers the whole site, not one scoped to a single model.

Event Fires when
entry.created An entry is created, or a deleted entry is restored.
entry.updated An entry’s data changes, it is moved to another folder, or it is reverted to an earlier revision.
entry.published An entry goes live, by an editor or by the scheduler.
entry.unpublished An entry stops being live, by an editor or by the scheduler.
entry.deleted An entry is archived or permanently deleted. Permanently deleting an entry that was already archived fires nothing more.
form.submitted A visitor submits a form and the entry is not classified as spam.

Some changes deliberately fire nothing: a save that changed no values (on models with Track revision history turned off, every save fires, because there is no previous revision to compare against), a save to a published entry (the edit is pending and fires entry.published when it goes live), a model change that rewrites many entries at once (renaming or removing a field), status changes on form entries, and anything on media or users. On a model set to always published, a create arrives as entry.created with status: "published" and no entry.published follows.

The Webhook events reference has the full payload for each event.

  1. Open the model’s or form’s Settings, or the site under Admin Settings → Site Management, and go to the Webhooks tab.
  2. Click Add webhook and fill in the dialog:
    • Name: shown in the console and sent in the payload as webhook.name.
    • URL: where Plenary POSTs. It must be https:// unless the instance runs with dev_mode: true.
    • Events: at least one.
    • Headers and Query parameters: optional extras sent with every delivery. Turn on Secret for credentials (see Secrets).
    • Fields: All fields (every field except private ones), Selected fields (only the ones you tick, private fields allowed), or No field data (identity and timestamps only).
  3. Save the page: Save model, Save form, or Save on the site. Webhook edits are staged with the rest of the page until you save.

Each webhook row has buttons to Pause/Resume it, open its Deliveries, edit it, and remove it. Pausing stops new deliveries from being queued; deliveries already queued still go out. Removing a webhook drops its queued deliveries.

Managing webhooks needs the content:webhooks:manage capability, which can be scoped to a single model or form. See Permissions.

A model’s or form’s webhooks are replaced as a whole array:

Terminal window
curl -X PUT https://your-instance.plenarycms.io/api/v1/models/MODEL_ID/webhooks \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"webhooks": [
{
"name": "Revalidate site",
"url": "https://www.example.com/api/plenary-webhook",
"events": ["entry.published", "entry.unpublished", "entry.updated", "entry.deleted"],
"headers": [{ "name": "X-Plenary-Secret", "value": "YOUR_SHARED_SECRET", "secret": true }],
"query": [],
"payload": { "mode": "all" },
"active": true
}
]
}'
Path For
PUT /api/v1/models/{model_id}/webhooks A content model
PUT /api/v1/forms/{form_id}/webhooks A form (events may only be ["form.submitted"])
GET, PUT /api/v1/sites/{site_key}/webhooks A site

MODEL_ID and form_id are UUIDs. PLENARY_ACCESS_TOKEN stands for a user session token or a private API key with content:webhooks:manage (send a key as X-API-KEY instead of Authorization).

Each webhook object:

Field Description
id Omit to create; include an existing id to update that webhook in place.
name Required.
url Required. Absolute http or https URL; https required outside dev_mode.
events Required, non-empty. Events valid for what the webhook is attached to.
headers, query Arrays of { "name", "value", "secret" }. Omit value on an existing secret to keep the stored one.
payload { "mode": "all" }, { "mode": "none" }, or { "mode": "selected", "fields": ["title", "slug"] }. Sites cannot use selected.
active Defaults to true. false pauses the webhook.

The response returns the saved array with secret values as null and "value_set": true. A model’s or form’s webhooks are also included, masked the same way, in GET /api/v1/models/{model_id} or GET /api/v1/forms/{form_id}. Updating the model itself with PUT /api/v1/models/{model_id} ignores any webhooks key, so round-tripping a model read cannot overwrite them.

Validation errors are 422 with vars.index naming the webhook: webhook_name_required, webhook_url_invalid, webhook_url_requires_https, webhook_events_empty, webhook_event_unknown, webhook_header_name_invalid, webhook_header_reserved, webhook_query_name_invalid, webhook_field_unknown, webhook_payload_mode_invalid.

Webhooks are not included in plenary metadata pull exports, so they are not part of models as code. An import leaves existing webhooks in place.

POST /api/plenary-webhook?token=… HTTP/1.1
Content-Type: application/json
User-Agent: Plenary
X-Plenary-Event: entry.published
X-Plenary-Webhook-Id: 4fd822a7-d09b-48bc-841a-3895adf8604f
X-Plenary-Delivery-Id: 52a2ec34-f4ea-4c34-a0af-3af34aabe612
X-Plenary-Attempt: 1
X-Plenary-Secret: YOUR_SHARED_SECRET

Your custom headers are added after Plenary’s. They cannot override Content-Type, User-Agent, any X-Plenary-* header, or the transport headers Host, Content-Length, Connection, Transfer-Encoding, and Upgrade; the webhook is rejected at save time with webhook_header_reserved if you try. Configured query parameters are merged into the URL’s existing query string.

The body is JSON. An entry event looks like this (trimmed; see Webhook events for every field):

{
"event": "entry.published",
"delivery_id": "52a2ec34-f4ea-4c34-a0af-3af34aabe612",
"occurred_at": "2026-10-07T09:15:56.878Z",
"webhook": { "id": "4fd822a7-d09b-48bc-841a-3895adf8604f", "name": "Revalidate site" },
"model": { "id": "ebdad6b3-cdca-4e2f-9aa0-714afaa36dfd", "key": "event" },
"entry": {
"id": "a57b9776-9300-4eae-82d6-86660b3b0466",
"site_key": "default",
"locale": "en-us",
"slug": "cafe-night",
"path": "/",
"status": "published",
"created_at": "2026-10-07T09:15:35.829Z",
"updated_at": "2026-10-07T09:15:56.877Z",
"published_at": "2026-10-07T09:15:56.877Z"
},
"actor": { "type": "user", "id": "6063d721-3d78-4f06-b983-0aed7300408b", "label": "editor@example.com" },
"changed": ["published_at", "status"],
"revision_id": "94a6df68-d2c9-41d6-888e-35a6669e6dea",
"data": { "title": "Café Night", "price": 15 }
}

data holds the stored values, not resolved ones: a reference arrives as its stored reference object and an image as its media id, never a URL.

Webhooks are delivered by a background worker, never inside the request that made the change. The editor’s save returns first, the delivery is queued, and the worker picks it up on its next sweep (every 10 seconds by default). By the time your endpoint receives a webhook, the change is already readable through the API.

Your endpoint’s answer Plenary’s outcome
Any 2xx Delivered. The body is read (up to 2 KB) and ignored.
400–499, except 408 and 429 Failed, no retry. The same request would get the same answer.
408, 429, any 5xx, a connection error, or no answer within 10 seconds Retried on the schedule below.
After failed attempt Next attempt in
1 30 seconds
2 2 minutes
3 10 minutes
4 1 hour
5 6 hours
6 none; the delivery is marked failed

That is six attempts over a little more than seven hours. The URL, headers, and query parameters are read from the webhook at each attempt, so fixing a wrong URL or rotating a secret repairs pending retries. The body is fixed when the event happens, so a retry describes the event as it was, not the entry as it is now.

Plenary can send the same delivery more than once, for example if the worker stops after your endpoint answered but before the result was recorded. Every attempt of one delivery carries the same X-Plenary-Delivery-Id (also in the body as delivery_id), and every delivery has a different one, even when one event fans out to several webhooks. Deduplicate on it.

By default several deliveries are sent at once, so two quick edits to the same entry can arrive in either order. Compare occurred_at against the last value you stored for that entry and ignore older events. An operator who needs strict order can set the instance to deliver one at a time, oldest first:

plenary.yaml
webhooks:
delivery: ordered # concurrent (default) | ordered
delivery_retention: 720h # how long delivery records are kept; 0 keeps them forever
sweep_interval: 10s # how often the worker looks for due deliveries

In ordered mode one slow endpoint delays every webhook on the instance. The per-attempt timeout and the retry schedule are fixed.

Mark a header or query parameter Secret for anything that is a credential. A secret value:

  • is never returned by any API: reads show null with "value_set": true, and the console offers Replace rather than showing it;
  • is replaced in revision history by a fingerprint, so history shows that a credential changed and when, without showing it;
  • is never written to the delivery log, which records header and query parameter names only.

Marking a value secret after it was saved does not remove it from revisions already recorded. Secret values are stored in plain text in Plenary’s database, like other outbound credentials.

Plenary does not sign webhook requests: there is no HMAC signature header. Authenticate deliveries with a shared secret instead:

  1. Generate a long random string, for example with openssl rand -hex 32.
  2. Add it to the webhook as a header (for example X-Plenary-Secret) or a query parameter (for example secret), with Secret turned on.
  3. In your endpoint, compare the received value to your copy in constant time and answer 401 if it does not match.

@plenary/client does this for you. parseWebhookRequest checks the method, compares the x-plenary-secret header (or the secret query parameter) in constant time, and shape-checks the body. It throws a PlenaryWebhookError whose status is the code to answer with (405, 401, or 400), so a bad request fails fast instead of being retried for seven hours. If the secret you pass is empty, for example an unset environment variable, it rejects every request with 500, and deliveries keep retrying until the secret is set.

app/api/plenary-webhook/route.ts
import {
isEntryWebhookPayload,
parseWebhookRequest,
PlenaryWebhookError,
} from "@plenary/client";
// Deliveries already handled, keyed by X-Plenary-Delivery-Id. Use a database
// or cache with a TTL in production; a module-level Set is per-process only.
const seen = new Set<string>();
export async function POST(request: Request) {
const secret = process.env.PLENARY_WEBHOOK_SECRET;
if (!secret) {
return Response.json({ error: "PLENARY_WEBHOOK_SECRET is not set" }, { status: 500 });
}
let payload;
try {
// Checks POST, compares the x-plenary-secret header (or ?secret=) in
// constant time, and shape-checks the JSON body.
payload = await parseWebhookRequest(request, { secret });
} catch (err) {
if (err instanceof PlenaryWebhookError) {
return Response.json({ error: err.message }, { status: err.status });
}
throw err;
}
if (seen.has(payload.delivery_id)) {
return Response.json({ duplicate: true });
}
seen.add(payload.delivery_id);
if (isEntryWebhookPayload(payload)) {
console.log(payload.event, payload.model.key, payload.entry.id, payload.changed);
} else {
console.log(payload.event, payload.form.key, payload.form_entry.id);
}
// Answer quickly; queue slow work instead of doing it here.
return Response.json({ received: true });
}

Use other header or parameter names with parseWebhookRequest(request, { secret, secretHeader: "x-my-header", secretQuery: "token" }). For Next.js cache revalidation, @plenary/next builds on this; see the revalidation example.

A correct endpoint:

  1. Answers within 10 seconds. Queue slow work (reindexing, sending email) and return 2xx immediately.
  2. Answers 2xx only when it accepted the event. A 200 that dropped the payload is invisible in the delivery log.
  3. Deduplicates on X-Plenary-Delivery-Id.
  4. Tolerates reordering by comparing occurred_at.
  5. Authenticates with the shared secret.
  6. Answers 4xx for requests it will never accept, so the delivery fails at once and shows up in the log, rather than retrying for seven hours.

There is no “send test” button. To test a webhook, make a change it subscribes to: create or edit an entry, or submit the form. During development, point the URL at a request inspector or a tunnel to your machine (with dev_mode: true on the instance, plain http URLs are allowed).

Then open the webhook’s Deliveries drawer. It lists the 50 most recent deliveries, newest first, each with its status (Queued, Sending, Delivered, Failed), attempt number, response code or error, duration, and next attempt time. Expand a row to see the exact payload sent and the names of the headers and query parameters that went with it; values are never shown. The webhooks list shows each webhook’s last delivery at a glance.

The same data is available from the API:

Path Returns
GET /api/v1/models/{model_id}/webhooks/{webhook_id}/deliveries The 50 most recent deliveries
GET /api/v1/models/{model_id}/webhooks/health The latest delivery per webhook

Forms use /api/v1/forms/{form_id}/… and sites /api/v1/sites/{site_key}/webhooks/… with the same suffixes. A delivery record:

{
"id": "079e17ec-a910-4665-bb42-9296a4554b50",
"webhook_id": "d58e835b-cd59-4f13-ad61-a271802a3a2d",
"entry_id": "5659896a-9736-4834-9a1c-b460cdee2349",
"event": "form.submitted",
"status": "pending",
"attempt": 1,
"header_names": ["X-Plenary-Secret"],
"query_names": [],
"error": "Post \"https://hooks.example.com/plenary\": dial tcp: connect: connection refused",
"payload": { "event": "form.submitted", "delivery_id": "079e17ec-a910-4665-bb42-9296a4554b50" },
"created_at": "2026-10-07T09:13:47.24Z",
"next_attempt_at": "2026-10-07T09:14:21.02Z"
}

status is pending, delivering, succeeded, or failed; status_code, duration_ms, and completed_at appear once there is a response. Delivery records are deleted after 30 days by default (webhooks.delivery_retention).

  • They cannot block or modify a change. A non-2xx answer only affects retries.
  • They do not reshape the body. Use field selection to send less; transform it on your side.
  • They do not fire for model or schema changes, form entry status changes, media, or users.