# Webhooks

URL: https://kywi-docs-production.up.railway.app/integrating/webhooks
Type: docPage

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.

## A layout or front-edit save fires no webhook

Most edits to a page's body do not go through the base content-update route at all: the layout editor and the front-edit overlay both save through a dedicated layout route that dispatches `content:afterLayoutUpdate` instead of `content:afterUpdate`. That event exists only to invalidate caches — it is not one of the eleven names above, so `WEBHOOK_EVENTS` does not include it and no endpoint can subscribe to it.

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.

## Store the secret at creation or replace the endpoint

A signing key has to stay recoverable for the server to sign with it, so it cannot be hashed at rest — instead it is returned exactly once and redacted everywhere else. Every later `GET`, `PUT` response and list row carries `secretSet: true` and no `secret`, and no route reveals or rotates it. Losing it means deleting the endpoint and creating another.

## 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 elided

## The payload names who did it

`data.kywi.user` carries the acting user's id, role, group names and site memberships on every content event. That is useful for an audit trail and it is a disclosure: whoever controls the receiving URL learns your editorial roster. Point endpoints at services you own, over TLS, and do not forward the raw body to a third party without stripping it.

## 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 }) }

## app/api/kywi-hook/route.ts

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

## A 500 from your endpoint is never retried

A connection failure or a timeout schedules a retry a minute out; an HTTP error response records the delivery as failed with its status code and schedules *nothing*, and the retry sweep only selects deliveries carrying a next-attempt time. If your receiver can be unhealthy while still answering, make it answer 2xx and queue internally — or reconcile from the delivery log.

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

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](/integrating/site-scoping-and-the-siteid-contract/)). Dispatch is scoped the same way: an event fires only the endpoints of the site whose content changed.
