# Alerts & Investigations webhooks

Alerts group risk occurrences that need attention. Investigations are the owned
human-review records opened from one or more alerts. The product and API use the
name Investigation. Webhook event names retain the established `case.*` prefix
so existing receivers do not break.

## Alert events

| Event | When it fires | Recommended handling |
|---|---|---|
| `alert.created` | A new actionable alert opens. | Create a linked review item. |
| `alert.updated` | Decision, score, occurrence count or status changes. | Update the existing item by `alertId`. |

```json
{
  "version": "2026-08-11",
  "id": "evt_alert_01",
  "type": "alert.created",
  "createdAt": "2026-08-15T17:32:00.000Z",
  "deliveryId": "del_alert_01",
  "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "OPEN", "decision": "REVIEW", "riskScore": 86, "occurrences": 1, "resolution": null }
}
```

```json
[
  { "type": "alert.updated", "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "IN_REVIEW", "decision": "REVIEW", "riskScore": 89, "occurrences": 3, "resolution": null } },
  { "type": "alert.updated", "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "RESOLVED", "decision": "ALLOW", "riskScore": 22, "occurrences": 3, "resolution": "FALSE_POSITIVE" } }
]
```

## Investigation events

| Event | When it fires |
|---|---|
| `case.created` | An investigation opens from related evidence. |
| `case.assigned` | An owner is assigned. |
| `case.review_started` | Human review begins. |
| `case.escalated` | Priority or review tier is escalated. |
| `case.resolved` | An analyst records a disposition. |
| `case.closed` | Operational work closes. |
| `case.reopened` | A closed investigation returns to review. |
| `case.sla_at_risk` | The due time is approaching. |
| `case.overdue` | The due time has passed. |

Every event uses the standard webhook envelope. Route it by `data.caseId`, then
retrieve `/api/v1/investigations/{caseId}` when your workflow needs the complete
current Investigation. `caseId` is retained inside webhook payloads as a stable
compatibility field.

```json
{
  "version": "2026-08-11",
  "id": "evt_investigation_01",
  "type": "case.assigned",
  "createdAt": "2026-08-15T17:35:00.000Z",
  "deliveryId": "del_investigation_01",
  "data": {
    "id": "evt_case_assigned_inv_01_current",
    "caseId": "inv_01",
    "entityId": "ent_01",
    "subject": { "type": "entity", "id": "ent_01" },
    "assigneeId": "usr_reviewer_01",
    "occurredAt": "2026-08-15T17:35:00.000Z"
  }
}
```

## Field reference

| Field | Type | Nullable | Meaning |
|---|---|---:|---|
| `alertId`, `caseId`, `entityId` | string | No where present | Stable alert, investigation and subject IDs. |
| `status` | string | No | Current lifecycle status shown in the examples. |
| `decision` | string | Yes | Alert decision such as `ALLOW`, `REVIEW` or `BLOCK`. |
| `riskScore` | number | Yes | Alert risk score. |
| `occurrences`, `alertCount` | integer | No | Grouped evidence or linked alert counts. |
| `resolution`, `disposition` | string | Yes | Recorded alert resolution or investigation outcome. |
| `priority` | string | No | For example `LOW`, `MEDIUM`, `HIGH` or `CRITICAL`. |
| `assigneeId` | string | Yes | Assigned user ID. |
| `dueAt` | ISO 8601 string | Yes | SLA deadline. |

Private notes, attachments, analyst evidence and SAR filing state are not included. There are no customer-facing `sar.*` events in the current catalogue.