Skip to content

Webhook Events

Plenary sends a webhook as an HTTP POST with a JSON body to the URL configured on a content model, a form, or a site. This page lists every event, the exact request, and how Plenary treats your response. For setup, authentication, and receiver code, see the Webhooks guide.

Event Fires when Available on Payload shape
entry.created An entry is created, or a deleted entry is restored from a revision. Content models, sites Entry
entry.updated An entry’s data changes, it moves to another folder, or it is reverted to an earlier revision. Content models, sites Entry
entry.published An entry goes live, by an editor or by the scheduler. Content models, sites Entry
entry.unpublished An entry stops being live, by an editor or by the scheduler. Content models, sites Entry
entry.deleted An entry is archived or permanently deleted. Permanently deleting an already-archived entry fires nothing more. Content models, sites Entry
form.submitted A visitor submits a form and the form entry is not classified as spam. Forms, sites Form

A content-model webhook may subscribe only to the five entry.* events, and a form webhook only to form.submitted. A site webhook may subscribe to all six and fires for every model and form whose entries belong to that site.

Change Why
A save where no value changed Not an event. Exception: on a model with Track revision history off, every save fires entry.updated.
A save to a published entry The edit is pending until it is published; nothing live changed. Publishing it fires entry.published. Discarding it fires nothing.
A model change that rewrites entries (renaming or removing a field) A schema change, not an edit to any entry.
Create on an always published model Fires entry.created with entry.status: "published"; no entry.published follows.
A spam-classified form entry Never dispatched.
A form entry’s status change or deletion No form entry triage events exist.
Media, user, model, or settings changes No events exist.
Any event while the webhook is paused Pausing stops new deliveries from being queued. Deliveries already queued are still sent.

There is no entry.restored event: a restore arrives as entry.updated (revert) or entry.created (undelete), and the revision named by revision_id records where it was restored from.

POST https://hooks.example.com/plenary?token=… HTTP/1.1
Content-Type: application/json
User-Agent: Plenary
X-Plenary-Event: entry.updated
X-Plenary-Webhook-Id: 4fd822a7-d09b-48bc-841a-3895adf8604f
X-Plenary-Delivery-Id: 27294cd2-22fc-48ca-839b-8e09f8803c14
X-Plenary-Attempt: 1
Header Value
Content-Type Always application/json.
User-Agent Always Plenary.
X-Plenary-Event The event name, the same as the body’s event.
X-Plenary-Webhook-Id The id of the webhook configuration that sent it.
X-Plenary-Delivery-Id The delivery id, the same as the body’s delivery_id. Stable across retries of one delivery and unique across deliveries. Use it to deduplicate.
X-Plenary-Attempt 1 on the first attempt, counting up on each retry.
Custom headers Every header configured on the webhook, including secret ones, applied after the headers above. They cannot override them.

Query parameters configured on the webhook are added to the URL; a configured parameter replaces one of the same name already in the URL.

Plenary does not sign requests. There is no signature header; authenticate with a shared secret in a custom header or query parameter. See Verify that a request came from Plenary.

Sent for all five entry.* events. A real entry.updated delivery:

{
"event": "entry.updated",
"delivery_id": "27294cd2-22fc-48ca-839b-8e09f8803c14",
"occurred_at": "2026-10-07T09:15:56.87Z",
"webhook": {
"id": "4fd822a7-d09b-48bc-841a-3895adf8604f",
"name": "Reindex events"
},
"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": "draft",
"created_at": "2026-10-07T09:15:35.829Z",
"updated_at": "2026-10-07T09:15:56.868Z"
},
"actor": {
"type": "user",
"id": "6063d721-3d78-4f06-b983-0aed7300408b",
"label": "editor@example.com"
},
"changed": ["data.price", "data.price_label", "data.title"],
"revision_id": "e7f5dcfc-7bc5-4a8c-a536-1c3a67f61a44",
"data": {
"title": "Café Night",
"url_slug": "cafe-night",
"phone": "+13035550142",
"price": 15,
"price_label": "$15.00",
"starts": "2026-11-01",
"ends": "2026-11-02"
}
}
Field Type Description
event string The event name.
delivery_id string Unique per delivery, stable across its retries. Equals X-Plenary-Delivery-Id.
occurred_at string RFC 3339 UTC time the event happened. Compare it to detect out-of-order deliveries.
webhook.id, webhook.name string The webhook configuration that sent this.
model.id, model.key string The entry’s content model. On a site webhook, use model.key to tell models apart.
entry.id string The entry id.
entry.site_key string The entry’s site.
entry.locale string The entry’s locale.
entry.slug string The entry’s slug. Omitted when it has none.
entry.path string The folder the entry is in (/ at the model root). It does not include the slug; join them to build a URL.
entry.status string draft or published.
entry.created_at, entry.updated_at string RFC 3339 UTC.
entry.published_at string When it was last published. Omitted if never published; kept after unpublishing.
actor.type string user, api_key, or system.
actor.id string The user or API key id. Omitted for system.
actor.label string A human-readable name: the user’s email, the API key’s name, or the subsystem (scheduler for scheduled publishing). Kept even if the user is later deleted.
changed string[] Paths that differ from the previous revision, such as data.title, status, published_at, path, folder_id. Always present. Empty for entry.created and entry.deleted, and empty when the model does not track revisions.
revision_id string The revision recording this change. Omitted when the model does not track revisions.
data object The entry’s field values, filtered by the webhook’s field selection (below). Omitted entirely for No field data.

Entry fields are always present (when the entry has a value for them); field selection only affects data.

Event entry describes changed
entry.created The new entry []
entry.updated The entry after the change The changed paths, for example ["data.title"], or ["folder_id", "path"] for a move
entry.published The entry after publishing; status is published For example ["published_at", "status"], or ["data.title", "published_at"] when pending changes went live on an entry that was already published. Never names draft.
entry.unpublished The entry after unpublishing; status is draft For example ["status"]
entry.deleted The entry as it was just before deletion, with its data []

For a scheduled publish or unpublish, actor is {"type": "system", "label": "scheduler"}.

data carries the stored values, never resolved or expanded ones, and they are the same on every event:

Field type Value in data
text, email, url, phone, select, date, time, datetime, color string
number number
boolean boolean
multi_select, tags array of strings
reference the stored reference object, for example {"content_id": "…", "model_key": "author"}
image {"media_id": "…", "alt": "…", "caption": "…"}; no URL is included
object, list, json, rich_text, blocks the stored JSON

Fetch anything you need resolved (URLs, referenced entries) from the Content API using the ids in the payload.

Webhook Fields setting payload.mode data contains
All fields all Every field except fields marked private.
Selected fields selected Only the named fields, private ones included. Not available on site webhooks.
No field data none The data key is absent.

Only fields the model currently defines are sent; values left over from removed fields are not.

Sent for form.submitted. A real delivery:

{
"event": "form.submitted",
"delivery_id": "079e17ec-a910-4665-bb42-9296a4554b50",
"occurred_at": "2026-10-07T09:13:47.24Z",
"webhook": {
"id": "d58e835b-cd59-4f13-ad61-a271802a3a2d",
"name": "Notify sales"
},
"form": {
"id": "4caadbec-0240-4782-8701-643f9fff4af9",
"key": "contact"
},
"form_entry": {
"id": "5659896a-9736-4834-9a1c-b460cdee2349",
"site_key": "default",
"status": "new",
"created_at": "2026-10-07T09:13:47.239Z",
"source": {
"ip": "203.0.113.7",
"user_agent": "Mozilla/5.0",
"referer": "https://example.com/contact"
}
},
"data": {
"name": "Jane Doe",
"email": "jane@example.com",
"topic": "sales",
"message": "Hello, I would like a demo."
}
}
Field Type Description
event string Always form.submitted.
delivery_id, occurred_at, webhook As in the entry payload.
form.id, form.key string The form.
form_entry.id string The form entry id.
form_entry.site_key string The site it was submitted to.
form_entry.status string Always new; spam entries do not fire.
form_entry.created_at string Submission time, RFC 3339 UTC.
form_entry.source object ip, user_agent, and referer captured from the submit request; each omitted when absent, and the whole object omitted when all are.
data object Submitted values, filtered by field selection as above.

A form payload has no actor, changed, or revision_id (the submitter is a visitor and form entries are not revisioned), and no slug, locale, path, or publish fields. The values are the stored ones, so a field hidden from public API keys is still sent when the webhook’s field selection includes it.

To tell the two shapes apart in code, check for entry versus form_entry; @plenary/client exports isEntryWebhookPayload and isFormWebhookPayload, and the types EntryWebhookPayload and FormWebhookPayload.

Your response Result
2xx Delivered. The response body is read up to 2 KB and otherwise ignored.
400–499 except 408 and 429 Failed permanently, no retry.
408, 429, 5xx Retried.
Connection error, TLS error, or no response within 10 seconds Retried.
Attempt Sent
1 On the worker’s next sweep after the event (every 10 seconds by default)
2 30 seconds after attempt 1 fails
3 2 minutes after attempt 2 fails
4 10 minutes after attempt 3 fails
5 1 hour after attempt 4 fails
6 6 hours after attempt 5 fails; if it fails, the delivery is marked failed

The body is built when the event happens and is identical on every attempt; only X-Plenary-Attempt changes. The URL, headers, and query parameters are read from the webhook configuration at each attempt. Removing a webhook drops its deliveries that have not been attempted yet.

Delivery is at-least-once: the same X-Plenary-Delivery-Id can arrive more than once. Under the default concurrent delivery mode, two events for the same entry can arrive in either order; with webhooks.delivery: ordered in plenary.yaml, deliveries go out one at a time, oldest first.

Each delivery is logged and visible in the webhook’s Deliveries drawer and at GET /api/v1/{models|forms}/{id}/webhooks/{webhook_id}/deliveries (or /api/v1/sites/{site_key}/webhooks/{webhook_id}/deliveries), newest first, 50 at most:

Field Description
id The delivery id (X-Plenary-Delivery-Id).
webhook_id, entry_id, event What was sent, for which entry.
status pending, delivering, succeeded, or failed.
attempt Attempts made so far.
header_names, query_names Names of the custom headers and query parameters sent. Values are never recorded.
status_code Your endpoint’s HTTP status, when it answered.
error Transport error, or the first 2 KB of a non-2xx response body.
duration_ms How long the last attempt took.
payload The exact body sent.
created_at, completed_at, next_attempt_at Timestamps.

Records are kept for 30 days by default (webhooks.delivery_retention in plenary.yaml; 0 keeps them forever).