In this section · 2 articles

Webhook payloads, headers and events

What a Laramin webhook request looks like: the method, every header, the JSON body for record events and named events, and the full list of events with what each one sends.

Applies to
Webhook Engine 2.2 and later
Who can do this
Developer
On this page

Each delivery is one HTTP POST to the destination's Endpoint URL. The examples below use made-up values and example.com addresses.

The request

HTTP
POST /laramin HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Laramin-WebhookEngine/2.2.0
X-Laramin-Timestamp: 1794052800
X-Laramin-Signature-Version: 2
X-Laramin-Signature: 3f1c…e09a
X-Laramin-Signature-Secondary: 9b27…41d0

{"event":"user.created","timestamp":1794052790,"data":{"id":42,"name":"Example User","email":"user@example.com"}}

Replace the highlighted values with your own.

Headers

HeaderAlways sentValue
Content-TypeYesapplication/json
User-AgentYesLaramin-WebhookEngine/<version>, for example Laramin-WebhookEngine/2.2.0. Tests from the Test Console send Laramin-WebhookEngine-Test/<version>.
X-Laramin-TimestampYesUnix time in seconds. With version 2, when this attempt was signed and sent. With version 1, when the event was queued (the same for every retry).
X-Laramin-SignatureYesLowercase hex HMAC-SHA256 of the signed string, using the destination's current secret.
X-Laramin-Signature-SecondaryOnly after the secret has been rotatedThe same, using the previous secret.
X-Laramin-Signature-VersionOnly with Sign the timestamp on2. Absent means version 1.
Custom headersIf the destination has anyAs set on the destination. A custom header can't replace any header above.

What the signature covers depends on the version. See Verify webhook signatures and handle retries.

The body

The body is JSON, encoded with PHP's default json_encode: no extra spaces, forward slashes escaped as \/, and non-ASCII characters escaped as \u sequences. Always verify the signature against the raw bytes you received, never against JSON you decoded and encoded again.

Record events

user.*, post.* and category.* events are sent when a record is created, changed or deleted. Their body has three keys:

JSON
{
  "event": "post.updated",
  "timestamp": 1794052790,
  "data": {
    "id": 17,
    "category_id": 3,
    "updated_at": "2026-11-07T10:13:10.000000Z"
  }
}
KeyWhat it is
eventThe event name: the record type in lowercase, a dot, then created, updated or deleted.
timestampUnix time in seconds when the event was queued. It doesn't change on retries or redeliveries.
dataThe record's stored fields after the change, with dates as text. Fields the record keeps hidden, such as passwords, remember tokens and two-factor secrets, are left out.
  • updated is sent each time the record is saved with a change, whoever or whatever made the change.
  • For records that go to a trash, deleted is sent when the record is moved to the trash, and data.deleted_at is set. Deleting it forever later sends deleted again.
  • data holds the record's own fields only, not related records. Text that's kept per language, such as a blog article's title, may be missing.

Named events

Named events are announced by an add-on with a payload it builds itself. The body is that payload, unchanged. Headless CMS payloads start with event and occurred_at (UTC, ISO 8601, to the second), followed by the event's own keys:

JSON
{
  "event": "hcms.entry.published",
  "occurred_at": "2026-11-07T10:13:10Z",
  "space": "website",
  "schema": "article",
  "entry": { "id": "01JC0EXAMPLE0000000000000", "slug": "hello-world" },
  "locale": "en",
  "schema_version": "1.3",
  "content_version": 12
}

They carry ids, keys and versions, never content. Fetch the content from the delivery API.

Event list

EventSent whenComes from
user.createdA user account is created. Listed as User Registered.Webhook Engine
user.updatedA user account is changed. Listed as User Details Changed.Webhook Engine
user.deletedA user account is deleted. Listed as User Removed.Webhook Engine
post.createdA blog article is first saved, including as a draft. It isn't sent again when the article is published. Listed as Article Published.Blog
post.updatedA blog article is changed. Listed as Article Changed.Blog
post.deletedA blog article is deleted. Listed as Article Removed.Blog
category.createdA blog category is created.Blog
category.updatedA blog category is changed.Blog
category.deletedA blog category is deleted.Blog
hcms.entry.publishedAn entry is published in a language. Keys: space, schema, entry (id, slug), locale, schema_version, content_version.Headless CMS
hcms.entry.unpublishedAn entry stops being delivered in a language. Same keys as hcms.entry.published.Headless CMS
hcms.collection.reorderedA collection's order changes. Keys: space, schema, content_version.Headless CMS
hcms.schema_version.publishedA schema records a new version. Keys: schema, version, change_class (initial, minor or major), spaces.Headless CMS
hcms.schema_version.retiredA schema version is retired. Keys: schema, major, spaces.Headless CMS
hcms.delivery.changedWhat applications receive changes, for example a space or channel is turned on or off. Keys: cause, space, schema, spaces, delivering, plus field or channel for some causes.Headless CMS
hcms.access.changedWho may read a space changes. Keys: cause, space, consumer_id, access_policy.Headless CMS

Blog and Headless CMS events are offered only while those add-ons are turned on.

What your endpoint should return

  • Any 2xx code means success. Return it as soon as you've checked the signature, and do slow work afterwards: your Laramin waits only 10 seconds.
  • Any other code, or no answer in time, is a failure and the delivery is retried.
  • Don't answer with a redirect. Give the destination the final address instead.
  • The response body is stored in the delivery log for administrators to read. Don't put secrets in it.