recovery.operation_started

A recovery began — run by the creator, by the platform on their behalf, or on demand for a healthy resource.

When this fires

The moment a recovery is opened in the ledger: an account relink or a switch to the backup account, a bot replacement, or a channel swap. The row exists from this moment because it is the quota ledger too — the allowance is spent here, and given back only if the recovery fails before changing anything.

A channel recovery absorbs every swap made inside its grace period into one operation, so a second channel swapped an hour after the first fires no second start; it fires recovery.resource_replaced under the same operation_id.

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.operation_started",
  "created_at": "2026-09-12T03:19:10Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "operation_id": "9a4d2e71-5b38-4c6f-8e12-3d7c9b0a5f21",
    "kind": "resources",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "automatic": true,
    "on_demand": false,
    "started_at": "2026-09-12T03:19:10Z"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `recovery.operation_started` 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 recovery.
`data.operation_id`	string UUID	The operation; read it with `GET /v1/recovery/operations/{operation}`.
`data.kind`	string	`account`, `bot` or `resources`.
`data.connector`	string \| null	The connector the recovery acts on.
`data.project_id`	string UUID \| null	The project, or null for an account recovery.
`data.automatic`	boolean	True when the platform ran it without the creator (automatic failover).
`data.on_demand`	boolean	True for a Swap & Grant of a healthy resource, which spends no allowance.
`data.started_at`	ISO 8601 timestamp	When it began — the moment that counts for the rolling allowance.

Caveats

Once per operation. Swaps absorbed into a running channel recovery fire no second start.
A recovery refused before the ledger row is written (quota spent, not the owner, plan lacks the feature) fires nothing.

recovery.operation_completed, recovery.operation_failed — how it ends.
Recovery events overview — back to family overview.