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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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
| Header | Always sent | Value |
|---|---|---|
Content-Type | Yes | application/json |
User-Agent | Yes | Laramin-, for example Laramin-. Tests from the Test Console send Laramin-. |
X- | Yes | Unix 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- | Yes | Lowercase hex HMAC-SHA256 of the signed string, using the destination's current secret. |
X- | Only after the secret has been rotated | The same, using the previous secret. |
X- | Only with Sign the timestamp on | 2. Absent means version 1. |
| Custom headers | If the destination has any | As 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"event": "post.updated",
"timestamp": 1794052790,
"data": {
"id": 17,
"category_id": 3,
"updated_at": "2026-11-07T10:13:10.000000Z"
}
}| Key | What it is |
|---|---|
event | The event name: the record type in lowercase, a dot, then created, updated or deleted. |
timestamp | Unix time in seconds when the event was queued. It doesn't change on retries or redeliveries. |
data | The 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. |
updatedis sent each time the record is saved with a change, whoever or whatever made the change.- For records that go to a trash,
deletedis sent when the record is moved to the trash, anddata.deleted_atis set. Deleting it forever later sendsdeletedagain. dataholds 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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
| Event | Sent when | Comes from |
|---|---|---|
user.created | A user account is created. Listed as User Registered. | Webhook Engine |
user.updated | A user account is changed. Listed as User Details Changed. | Webhook Engine |
user.deleted | A user account is deleted. Listed as User Removed. | Webhook Engine |
post.created | A 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.updated | A blog article is changed. Listed as Article Changed. | Blog |
post.deleted | A blog article is deleted. Listed as Article Removed. | Blog |
category.created | A blog category is created. | Blog |
category.updated | A blog category is changed. | Blog |
category.deleted | A blog category is deleted. | Blog |
hcms. | An entry is published in a language. Keys: space, schema, entry (id, slug), locale, schema_version, content_version. | Headless CMS |
hcms. | An entry stops being delivered in a language. Same keys as hcms.. | Headless CMS |
hcms. | A collection's order changes. Keys: space, schema, content_version. | Headless CMS |
hcms. | A schema records a new version. Keys: schema, version, change_class (initial, minor or major), spaces. | Headless CMS |
hcms. | A schema version is retired. Keys: schema, major, spaces. | Headless CMS |
hcms. | What 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. | Who 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
2xxcode 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.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.