> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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.

```json theme={null}
{
  "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](/api-reference/webhooks/verification).


## Related topics

- [List supported webhook events](/api-reference/webhooks/list-events.md)
- [Set up webhooks](/api-reference/webhooks/setup.md)
- [Verify and process webhooks](/api-reference/webhooks/verification.md)
- [All endpoints](/api-reference/endpoints.md)
- [Developer quickstart](/api-reference/quickstart.md)