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.
Events
Section titled “Events”| 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.
What does not fire
Section titled “What does not fire”| 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.
Request
Section titled “Request”POST https://hooks.example.com/plenary?token=… HTTP/1.1Content-Type: application/jsonUser-Agent: PlenaryX-Plenary-Event: entry.updatedX-Plenary-Webhook-Id: 4fd822a7-d09b-48bc-841a-3895adf8604fX-Plenary-Delivery-Id: 27294cd2-22fc-48ca-839b-8e09f8803c14X-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.
Entry payload
Section titled “Entry payload”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.
Per event
Section titled “Per event”| 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"}.
Values in data
Section titled “Values in data”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.
Field selection
Section titled “Field selection”| 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.
Form payload
Section titled “Form payload”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.
Responses and retries
Section titled “Responses and retries”| 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.
Delivery records
Section titled “Delivery records”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).
Related
Section titled “Related”- Webhooks guide
- Forms guide
@plenary/client:parseWebhookRequest,verifyWebhookSecret, payload types- Revalidation example