Webhooks
Eleven lifecycle events POST a signed body to your endpoint: `X-Kywi-Signature` is an HMAC-SHA256 of the exact JSON sent, and the secret is shown only once.
An endpoint is a URL, a signing secret and a list of event names. Kywi POSTs to it when one of those events fires on the site the endpoint belongs to, signs the body with the secret, and records the attempt.
The eleven events you can subscribe to
These eleven event names are the entire set a webhook endpoint can
subscribe to; there is no wildcard and no event for users, media, menus or versions.
The events array is not checked against this list, so a misspelled name is
silently accepted and never fires.
| Name | Type | Default | Description |
|---|---|---|---|
content:afterCreate | content | — | A node was created, in any status. |
content:afterUpdate | content | — | Fields changed through the base content-update route — publish, unpublish and layout/front-edit saves fire different events; see the warning below. |
content:afterDelete | content | — | A node was trashed. |
content:afterPublish | content | — | Status became published, including through a changeset. |
content:afterUnpublish | content | — | Status left published. |
comment:afterCreate | comment | — | A comment was submitted, before moderation. |
comment:afterApprove | comment | — | A comment was approved. |
comment:afterDelete | comment | — | A comment was deleted. |
category:afterCreate | category | — | A category was created. |
category:afterUpdate | category | — | A category was edited. |
category:afterDelete | category | — | A category was deleted. |
/api/v1/webhooks?siteId=<site>Site adminCreates the endpoint and returns the only response that will ever contain
the secret. secret must be at least 16 characters; Kywi does not generate
one.
{
"data": {
"id": "b25d9ce5-bd4e-4cdf-af78-d1f2f3ca48f0",
"siteId": "1821c45b-27fa-4b9f-b70e-659650711133",
"url": "https://example.test/hooks/kywi",
"secret": "the-only-time-you-see-this",
"events": ["content:afterPublish"],
"isActive": true,
"createdBy": "7162df23-4e1e-4e50-b2db-4486a1a9cf0d",
"createdAt": "2026-09-02T22:59:09.766Z",
"updatedAt": "2026-09-02T22:59:09.766Z"
}
}What arrives at your URL
X-Kywi-Event repeats the event name, X-Kywi-Signature is the hex HMAC-SHA256 of the request body under your secret, and the body is the envelope below. The content object is the whole stored row — 74 keys on the delivery captured here, including the full layout document and every base-type column that does not apply, at null.
{
"event": "content:afterUpdate",
"data": {
"content": {
"id": "f5ef2496-9590-402f-9d37-0bc3f094881b",
"siteId": "1821c45b-27fa-4b9f-b70e-659650711133",
"path": "/integrating/webhooks/",
"slug": "webhooks",
"title": "Webhooks",
"status": "draft",
"contentTypeName": "docPage",
"layout": { "regions": { "main": [] } },
"updatedAt": "2026-09-02T22:52:22.186Z"
},
"contentType": "docPage",
"kywi": {
"cache": {},
"user": {
"id": "7162df23-4e1e-4e50-b2db-4486a1a9cf0d",
"role": "superAdmin",
"groups": ["Administrators"],
"siteMemberships": ["61ad1916-…", "f9df3338-…"]
}
}
},
"timestamp": 1788389949814
}Verifying the signature
Sign the bytes you received, not an object you re-serialized from them. Kywi HMACs the exact string it puts on the wire, so any reformatting — key reordering, a different float or whitespace rendering — produces a different digest against the same logical payload. Read the raw body first, verify, then parse.
import { createHmac, timingSafeEqual } from 'node:crypto'
export async function POST(req: Request) {
const raw = await req.text() // before any JSON.parse
const sent = req.headers.get('x-kywi-signature') ?? ''
const expected = createHmac('sha256', process.env.KYWI_HOOK_SECRET!)
.update(raw)
.digest('hex')
const a = Buffer.from(sent, 'hex')
const b = Buffer.from(expected, 'hex')
if (a.length !== b.length || !timingSafeEqual(a, b)) {
return new Response('bad signature', { status: 401 })
}
const { event, data, timestamp } = JSON.parse(raw)
// Kywi does not enforce a timestamp window — reject stale ones here if replay matters.
return Response.json({ ok: true })
}Delivery, failure, and the retry you have to switch on
Kywi waits 10 seconds and treats any 2xx as delivered. Return quickly and do the work afterwards: a slow handler is a timeout, and a timeout is a failure.
That first retry is a flat one-minute wait, hardcoded on the failure path rather than computed. Every retry after that goes through the retry worker, which does compute a backoff: 2, 4, 8, then 16 minutes and flat from there, up to ten attempts total. Both stages only happen if the host app started the retry worker: the reference app does, on a 60-second sweep, and the generated scaffold does not. Tune or disable it with webhooks.retryIntervalSeconds and webhooks.maxAttempts.
/api/v1/webhooks/:id/deliveries?siteId=<site>&limit=50Site adminThe delivery log for one endpoint, newest first — each row carries the
event, the stored payload, status, httpStatus,
attempts and nextRetryAt. This is the reconciliation surface: a
row that is failed with a null nextRetryAt is one nothing will
send again.
Every webhook route wants siteAdmin and resolves its site from ?siteId= (Site scoping and the siteId contract). Dispatch is scoped the same way: an event fires only the endpoints of the site whose content changed.