Skip to content

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.

NameTypeDefaultDescription
content:afterCreatecontent—

A node was created, in any status.

content:afterUpdatecontent—

Fields changed through the base content-update route — publish, unpublish and layout/front-edit saves fire different events; see the warning below.

content:afterDeletecontent—

A node was trashed.

content:afterPublishcontent—

Status became published, including through a changeset.

content:afterUnpublishcontent—

Status left published.

comment:afterCreatecomment—

A comment was submitted, before moderation.

comment:afterApprovecomment—

A comment was approved.

comment:afterDeletecomment—

A comment was deleted.

category:afterCreatecategory—

A category was created.

category:afterUpdatecategory—

A category was edited.

category:afterDeletecategory—

A category was deleted.

POST/api/v1/webhooks?siteId=<site>Site admin

Creates 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.

201
{
  "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.

a real content:afterUpdate delivery, content elidedjson
{
  "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.

app/api/kywi-hook/route.tsts
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.

GET/api/v1/webhooks/:id/deliveries?siteId=<site>&limit=50Site admin

The 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.