Webhooks

Webhook event reference

Event names, payload fields, and delivery headers.

Subscribe to explicit event names when creating an endpoint. Retrieve the supported catalog from your API deployment:

curl --fail-with-body --silent --show-error \
  https://api.getkato.io/v1/webhooks/events \
  -H "Authorization: Bearer $KATO_API_KEY"

This request requires webhooks:read and returns a data array of strings.

Supported events

Resource	Events
Record	`record.created`, `record.updated`, `record.deleted`
Task	`task.created`, `task.updated`, `task.deleted`, `task.status_changed`, `task.assigned`, `task.unassigned`
Comment	`comment.created`, `comment.updated`, `comment.deleted`
Meeting	`meeting.created`, `meeting.updated`, `meeting.rescheduled`, `meeting.status_changed`, `meeting.deleted`
Document	`document.created`, `document.updated`, `document.deleted`, `document.sent`, `document.signed`, `document.approved`, `document.completed`, `document.declined`, `document.voided`, `document.expired`
Time Entry	`time_entry.created`, `time_entry.updated`, `time_entry.deleted`
Invoice	`invoice.created`, `invoice.updated`, `invoice.deleted`, `invoice.sent`, `invoice.viewed`, `invoice.paid`, `invoice.voided`, `invoice.uncollectible`
Payment	`payment.created`, `payment.updated`, `payment.deleted`
Retainer	`retainer.created`, `retainer.updated`, `retainer.paused`, `retainer.resumed`, `retainer.canceled`, `retainer.usage_threshold_reached`, `retainer.cycle_completed`, `retainer.cycle_failed`

An event being available does not imply a corresponding public REST endpoint exists. The general API currently exposes objects, records, tasks, and webhook management.

Payload envelope

This is an illustrative record.updated delivery. IDs and field values vary by workspace.

{
  "version": 1,
  "id": "event_example",
  "type": "record.updated",
  "createdAt": "2026-09-03T17:00:00.000Z",
  "workspaceId": "workspace_example",
  "data": {
    "entityType": "record",
    "entityId": "record_example",
    "action": "updated",
    "actorId": "user_example",
    "metadata": {},
    "source": {
      "kind": "api"
    },
    "entity": {
      "id": "record_example",
      "type": "record"
    }
  }
}

Field	Meaning
`version`	Payload schema version; currently `1`
`id`	Stable event ID; use for deduplication
`type`	Subscribed event name
`createdAt`	Event timestamp as an ISO 8601 string
`workspaceId`	Workspace that produced the event
`data.entityType` / `data.entityId`	Entity affected
`data.action`	Action that produced the event
`data.actorId`	Actor identifier; may identify the system
`data.metadata`	Sanitized event-specific context
`data.source`	Origin: `user`, `api`, `automation`, `integration`, or `system`; may include `provider` and `id`
`data.entity`	Allowlisted entity summary, not a complete REST resource
`data.changedFields`	Optional array of changed field names
`data.before` / `data.after`	Optional sanitized change snapshots

Treat optional fields as optional. Do not assume every event carries a full record, document body, or field-values map. If your handler needs current record or task state, retrieve it through the API with the relevant read scope.

Delivery headers

Header	Meaning
`X-Kato-Signature`	`t=<Unix seconds>,v1=<hex HMAC-SHA256>`
`X-Kato-Event`	Event type
`X-Kato-Event-Id`	Stable event ID
`X-Kato-Delivery-Id`	Delivery record identifier

After verification, use the signed payload for processing and deduplication. The signature covers the timestamp and body; the other headers are useful for diagnostics.

Change handling

Record archival produces record.deleted. Task status changes have task.status_changed, and assignment and removal have task.assigned and task.unassigned. Subscribe to the specific transitions your integration needs instead of assuming all changes use updated.

Kato retains a compatibility fallback for older subscribers: an unassignment may arrive as task.assigned when an endpoint subscribes to task.assigned but not task.unassigned. New integrations should subscribe to both and inspect the payload action.

Webhook deliveries can be duplicated or reordered. For a current-state mirror, fetch the latest accessible record or task when processing an event rather than overwriting it blindly with a potentially older summary. See verification and reliable processing.

Updated September 3, 2026

Something missing? Let us know.