Webhooks

Register an endpoint

Use a key with webhook:manage. Save the returned webhook.id and webhook.secret_key securely.

curl --fail-with-body "$KITA_CAPTURE_BASE/webhooks" \
  -H "Authorization: Bearer $KITA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-app.example/webhooks/kita","events":["document.completed","document.failed"]}'

Test delivery with POST /webhooks/{id}/test. Inspect attempts with GET /webhooks/{id}/deliveries.

Verify signatures

Registered deliveries include X-Kita-Signature: t=TIMESTAMP,v1=HEX_DIGEST. The digest is HMAC-SHA256 of TIMESTAMP.RAW_BODY, using the webhook secret. Verify the raw bytes before parsing (do not reserialize the JSON), compare digests in constant time, and reject timestamps outside a five-minute tolerance.

Record X-Kita-Delivery-Id to avoid processing a retry twice. Acknowledge promptly, then fetch the document with your API key. Delivery order is not guaranteed; check the document's current status.

Per-upload callbacks

You can also pass webhook_url on an upload; it still returns 202 immediately. Do not assume the registered webhook secret applies to per-upload callbacks. Use the callback to trigger an authenticated result lookup, with polling as a fallback.

Management