# Continuous Monitoring webhooks

For a minimal integration, subscribe to `monitoring.delta.detected`.
Add `monitoring.run.failed` when your operations team must react to an incomplete check.
Do not subscribe to high-volume `monitoring.run.completed` unless your system needs every successful run.

## Events

| Event | When it fires |
| --- | --- |
| `monitoring.subscription.started` | Monitoring becomes active for an Entity. |
| `monitoring.subscription.paused` | Scheduled monitoring is paused. |
| `monitoring.subscription.resumed` | A paused subscription becomes active. |
| `monitoring.subscription.ended` | A subscription is permanently turned off. |
| `monitoring.subscription.updated` | An Entity's policy or frequency changes. |
| `monitoring.run.completed` | One monitoring run completed. |
| `monitoring.run.failed` | One monitoring run could not complete. |
| `monitoring.delta.detected` | Monitoring found one or more material changes. |

`monitoring.failed` is not a public event name.

## Exact V2 delta envelope

```json
{
  "version": "2026-08-11",
  "id": "evt_monitoring_delta_01",
  "type": "monitoring.delta.detected",
  "createdAt": "2026-08-26T17:00:00.000Z",
  "deliveryId": "del_monitoring_delta_01",
  "data": {
    "subscriptionId": "sub_01",
    "entityId": "ent_01",
    "externalUserId": "customer_42",
    "subject": {
      "entityId": "ent_01",
      "externalUserId": "customer_42",
      "identityId": "identity_01",
      "type": "individual"
    },
    "detectedAt": "2026-08-26T17:00:00.000Z",
    "deltas": [
      { "type": "SANCTIONS_MATCH", "direction": "ADDED", "severity": "HIGH" }
    ]
  }
}
```

This is the complete V2 envelope. Product fields live directly inside `data`.

## Run failure example

```json
{
  "version": "2026-08-11",
  "id": "evt_monitoring_failed_01",
  "type": "monitoring.run.failed",
  "createdAt": "2026-08-26T17:04:00.000Z",
  "deliveryId": "del_monitoring_failed_01",
  "data": {
    "subscriptionId": "sub_01",
    "entityId": "ent_01",
    "externalUserId": "customer_42",
    "failureCode": "provider_unavailable",
    "failedAt": "2026-08-26T17:04:00.000Z"
  }
}
```

## Public data contract

| Field | Events | Meaning |
| --- | --- | --- |
| `subscriptionId` | All | Customer-addressable monitoring subscription. |
| `entityId`, `externalUserId`, `subject` | Entity-related events | Customer correlation without internal source data. |
| `status` | Subscription lifecycle | `active`, `paused` or `ended`. |
| `frequency` | Subscription updated | Effective frequency, policy default, Entity override and source. |
| `materialChange`, `completedAt` | Run completed | Whether the successful run found a material change and when it completed. |
| `failureCode`, `failedAt` | Run failed | Stable failure classification and time. |
| `deltas`, `detectedAt` | Delta detected | Customer-visible material changes and detection time. |

Internal `policyVersionId`, `monitoringRunId` and `assessmentId` fields are not included.
Read current state and history from `GET /api/v1/monitoring/subscriptions/{subscriptionId}`.

Verify the raw request body, deduplicate by envelope `id`, return `2xx` quickly, and use the read API whenever current state matters.