# Webhook Events

> Every event SOAT emits, the resource type each belongs to, and what it means.

{/* This page is generated by packages/website/scripts/generateWebhookEventsPage.ts — do not edit by hand. */}

# Webhook Events

The 53 events SOAT emits, grouped by the `resource_type` each carries. A [webhook](./modules/webhooks.md) subscribes to them by exact name, by `<prefix>.*`, or to all of them with `*`.

Each event arrives as the envelope described in [Webhooks → Event Payload](./modules/webhooks.md#event-payload): the name below is the `event` field and the `X-Soat-Event` header, the heading above each table is the `resource_type` field, and `data` carries the resource in the same shape the REST API returns it.

An orchestration [`emit_event` node](./modules/orchestrations.md) also emits events, under whatever name the template author chose. Those are not listed here — they are yours, not SOAT's — and they carry `resource_type: orchestration_run`.

## `agent`

| Event | Description |
| --- | --- |
| `agents.created` | An agent was created. |
| `agents.updated` | An agent was updated. |
| `agents.deleted` | An agent was deleted. |

## `approval`

| Event | Description |
| --- | --- |
| `approvals.created` | An approval request was raised and is pending. |
| `approvals.approved` | A pending approval was approved. |
| `approvals.rejected` | A pending approval was rejected. |
| `approvals.expired` | A pending approval passed its deadline unanswered. |

## `audit`

| Event | Description |
| --- | --- |
| `audit.entry_created` | An audit entry was recorded. |

## `conversation`

| Event | Description |
| --- | --- |
| `conversations.created` | A conversation was created. |
| `conversations.updated` | A conversation was updated. |
| `conversations.deleted` | A conversation was deleted. |

## `conversation_message`

| Event | Description |
| --- | --- |
| `conversations.message.created` | A message was added to a conversation. |
| `conversations.message.generated` | An assistant message was generated in a conversation. |
| `conversations.message.deleted` | A message was removed from a conversation. |

## `document`

| Event | Description |
| --- | --- |
| `documents.created` | A document was created. |
| `documents.updated` | A document was updated. |
| `documents.deleted` | A document was deleted. |
| `documents.ingested` | A document finished ingestion and is indexed (`status=ready`); the payload carries the document plus its final `chunk_count`. |
| `documents.ingest_failed` | A document ingestion settled in failure (`status=failed`); the payload carries the document plus the `error` reason (e.g. `FILE_PARSE_FAILED`, `INGESTION_TIMEOUT`). |

## `eval_run`

| Event | Description |
| --- | --- |
| `eval_run.completed` | An eval run reached a terminal status with its items scored; carries the pass/fail verdict consumed by eval-gated promotion. |
| `eval_run.failed` | An eval run could not be executed to completion (infrastructure failure). |

## `exception`

| Event | Description |
| --- | --- |
| `exceptions.created` | An exception was filed. |

## `file`

| Event | Description |
| --- | --- |
| `files.created` | A file was uploaded. |
| `files.updated` | A file was updated. |
| `files.deleted` | A file was deleted. |

## `generation`

| Event | Description |
| --- | --- |
| `agents.generation.requires_action` | An agent generation paused for a client-side tool result. |
| `agents.generation.completed` | An agent generation completed. |
| `agents.generation.failed` | An agent generation failed. |
| `generations.content_purged` | A generation's content was redacted, leaving its auditable skeleton. |
| `generations.chain_limit` | A continuation chain reached its generation budget and was refused. |

## `guardrail`

| Event | Description |
| --- | --- |
| `guardrail.tripwire` | A guardrail tripwire aborted a tool call. |

## `orchestration_run`

| Event | Description |
| --- | --- |
| `orchestration_runs.started` | An orchestration run started. |
| `orchestration_runs.awaiting_input` | An orchestration run paused waiting for input. |
| `orchestration_runs.succeeded` | An orchestration run succeeded. |
| `orchestration_runs.failed` | An orchestration run failed. |

## `quota`

| Event | Description |
| --- | --- |
| `quota.exceeded` | A quota limit was exceeded. |

## `session`

| Event | Description |
| --- | --- |
| `sessions.created` | A session was created. |
| `sessions.updated` | A session was updated. |
| `sessions.deleted` | A session was deleted. |
| `sessions.tags.updated` | A session's tags were replaced. |
| `sessions.generation.started` | A session generation started. |
| `sessions.generation.requires_action` | A session generation paused for a client-side tool result. |
| `sessions.generation.completed` | A session generation completed. |

## `task`

| Event | Description |
| --- | --- |
| `tasks.created` | A task was created. |
| `tasks.transitioned` | A task moved to a new state. |
| `tasks.closed` | A task reached a terminal state. |
| `tasks.stalled` | A task exceeded its stall threshold without progress. |
| `tasks.approval_failed` | A task's approval gate was rejected or expired. |
| `tasks.automation_retrying` | A task's automation is being retried. |
| `tasks.automation_rejected` | A task's automation rejected the task. |
| `tasks.automation_unrouted` | A task matched no automation route. |

## `trace`

| Event | Description |
| --- | --- |
| `traces.content_purged` | A trace's content was redacted, leaving its auditable skeleton. |

## `usage_threshold`

| Event | Description |
| --- | --- |
| `usage.threshold_crossed` | A usage threshold was crossed. |