Webhooks

Register, list, and delete webhooks that POST to your endpoint when pages change.

A webhook sends a signed JSON POST to your URL whenever a file matching its path pattern changes. Use webhooks to trigger CI, sync to another system, or notify a chat channel. For in-process consumers, the SSE event stream is simpler.

Webhooks are off by default. Turn them on in config:

.kiwi/config.toml

[webhooks]
enabled = true
max_workers = 4   # concurrent deliveries
max_retries = 5   # default 5

When webhooks are off, every endpoint on this page returns 503 with webhooks not enabled. See Webhooks for delivery details.

Register a webhook

Create a webhook and return its signing secret. The secret is only returned here, so store it.

POST /api/kiwi/webhooks

url · string · required

Endpoint that receives POST requests.

path_glob · string · required

Which paths trigger the webhook. ** matches everything, concepts/** matches everything under concepts/, and other patterns use shell glob rules against the path without a leading slash (for example runbooks/*.md).

event_types · string[]

Only fire for these event types. Omit to receive all. See Event payload.

curl -X POST 'http://localhost:3333/api/kiwi/webhooks' \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hook", "path_glob": "concepts/**", "event_types": ["write", "delete"]}'

Returns 201 on success and 400 if url or path_glob is missing.

id · string

Webhook ID, prefixed wh_.

url · string

Registered endpoint.

path_glob · string

Path pattern.

secret · string

Signing secret, prefixed whsec_. Only returned at creation.

created_at · string

Creation time (RFC 3339).

enabled · boolean

Whether the webhook fires.

event_types · string[]

Event filter. Omitted when the webhook receives every type.

{
  "id": "wh_3f9a1c7e2b4d6a80",
  "url": "https://example.com/hook",
  "path_glob": "concepts/**",
  "secret": "whsec_8c1e0f4b9a7d2e6c3b5a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c",
  "created_at": "2026-10-19T14:30:00Z",
  "enabled": true,
  "event_types": ["write", "delete"]
}

List webhooks

Return every registered webhook, without secrets.

GET /api/kiwi/webhooks

curl 'http://localhost:3333/api/kiwi/webhooks'

Returns a JSON array with the fields from Register a webhook, minus secret.

[
  {
    "id": "wh_3f9a1c7e2b4d6a80",
    "url": "https://example.com/hook",
    "path_glob": "concepts/**",
    "created_at": "2026-10-19T14:30:00Z",
    "enabled": true,
    "event_types": ["write", "delete"]
  }
]

Delete a webhook

Remove a webhook by ID.

DELETE /api/kiwi/webhooks/:id

id · string · required

Webhook ID.

curl -X DELETE 'http://localhost:3333/api/kiwi/webhooks/wh_3f9a1c7e2b4d6a80'

Returns 204 No Content on success and 404 if the ID does not exist.

Event payload

Each delivery is a POST with a JSON body. A change that touches several files sends one delivery per file.

type · string

write, delete, bulk, rollback, or transition (a workflow state change).

path · string

Changed file.

actor · string

Who made the change.

timestamp · string

Event time (RFC 3339).

field · string

For transition: the frontmatter field that changed.

from_state · string

For transition: previous value.

to_state · string

For transition: new value.

{
  "type": "write",
  "path": "concepts/auth.md",
  "actor": "agent:docs-writer",
  "timestamp": "2026-10-19T14:31:02Z"
}

Failed deliveries (network errors or non-2xx responses) are retried after 5 seconds, 30 seconds, 2 minutes, 15 minutes, and 1 hour, up to max_retries.

Verify signatures

Every delivery carries Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature) and a simpler X-Kiwi-Signature-256 header. For the simple header, compute an HMAC-SHA256 of the raw request body with the full secret string as the key, and compare:

X-Kiwi-Signature-256: sha256=<hex digest>

verify.py

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Related

Webhooks concepts

Delivery model and use cases.

Workflows

State changes that send transition events.