recovery.incident_opened

A health probe found the creator's sign-in account unreachable, a project's bot refused by the platform, or a channel or group gone or no longer administered.

When this fires

The hourly probes check every bot, every channel and group a project sells, and the creator's own sign-in account. When one comes back banned, deleted, or stripped of the rights the bot needs, an incident opens in the recovery ledger and this event fires — once. A probe that finds the same broken thing on its next run reopens nothing and fires nothing; the incident stays open until it resolves. Undoing an account relink also opens an account incident (reason: relink_disputed) so support reviews the dispute.

Required ability

project-recovery:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "recovery.incident_opened",
  "created_at": "2026-09-12T03:19:04Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "incident_id": "6f1e9b27-4c3a-4d58-9e02-b7a1c5d38f64",
    "kind": "resources",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
    "reason": "chat_not_found",
    "detected_at": "2026-09-12T03:19:04Z"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `recovery.incident_opened` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID \| null	Project this event belongs to; null for an account incident.
`data.incident_id`	string UUID	The incident; read it with `GET /v1/recovery/incidents/{incident}`.
`data.kind`	string	`account` (the creator's sign-in account), `bot` (a project's installation) or `resources` (a channel or group).
`data.connector`	string \| null	The connector the broken thing lives on, such as `telegram`.
`data.project_id`	string UUID \| null	The project, for `bot` and `resources` incidents; null for `account`.
`data.resource_id`	string UUID \| null	The channel or group, for `resources` incidents; null otherwise.
`data.reason`	string \| null	The connector's code for what it saw (`chat_not_found`, `bot_removed`, …); the API's `reason_label` puts it into words.
`data.detected_at`	ISO 8601 timestamp	When the probe saw it.

Caveats

One event per incident. The ledger opens one incident per subject and keeps it open, so a subject that stays broken for a week fires this once, not hourly.
A restriction the platform reports as "still reachable" opens nothing: only a verdict that warrants a replacement counts. See How detection works.

recovery.incident_resolved — the same incident healing or being fixed.
project.resource.status_changed — the health verdict that precedes a resources incident.
Recovery events overview — back to family overview.