connector.doctor_completed

The connector doctor ran on an installation and found something different from the previous run.

When this fires

The creator pressed Run Doctor on the Connectors tab or the connector's page, an integration called POST …/installation/doctor or run_connector_doctor, or the operator's sweep ran, and the report differs from the one kept on the installation: a finding appeared, disappeared or changed severity or state. A run that finds exactly what the last one found fires nothing, so a nightly sweep is quiet until something moves. The installation's own verification inside the run still fires connector.status_changed when the state moved.

Required ability

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

Payload

{
  "id": "evt_01HX...",
  "type": "connector.doctor_completed",
  "created_at": "2026-09-12T10:07:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "connector": "telegram",
    "installation_id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "ran_at": "2026-09-12T10:07:00+00:00",
    "healthy": false,
    "critical": 1,
    "warnings": 0,
    "findings": [
      { "key": "installation", "kind": "installation", "severity": "ok", "subject": "Research Bot", "state": "connected", "message": "The connector still answers for this installation.", "creator_actionable": false, "fix_url": null, "resource_id": null },
      { "key": "resource:b73c5f21-9d80-4a6e-8215-4f70ce13a9d6", "kind": "resource", "severity": "critical", "subject": "Premium Channel", "state": "not_member", "message": "The bot was removed from this channel.", "creator_actionable": true, "fix_url": "https://app.subscriby.net/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/resources", "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6" }
    ]
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `connector.doctor_completed` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID	The project the installation belongs to.
`data.connector`	string	The connector key.
`data.installation_id`	string UUID	The installation examined.
`data.project_id`	string UUID	The project, repeated inside the payload.
`data.ran_at`	ISO 8601 timestamp	When the doctor ran.
`data.healthy`	boolean	Whether every finding is `ok`.
`data.critical`	integer	Findings the connector can no longer act on.
`data.warnings`	integer	Findings the connector could not confirm.
`data.findings`	array	Every check, the installation first, then one per gated resource.
`data.findings[].key`	string	`installation`, or `resource:<resource id>`.
`data.findings[].kind`	string	`installation` or `resource`.
`data.findings[].severity`	string	`ok`, `warning` or `critical`.
`data.findings[].subject`	string	What was checked, as the creator names it.
`data.findings[].state`	string	The connector's word for how it stands: an installation state, or a space access state.
`data.findings[].message`	string	One sentence in the creator's language.
`data.findings[].creator_actionable`	boolean	Whether the creator can fix it themselves.
`data.findings[].fix_url`	string \| null	Where they go to fix it, when there is a page.
`data.findings[].resource_id`	string \| null	The resource, for a resource finding.

Caveats

The first run on an installation fires this event, because there is no earlier report to match; a repeat with the same findings does not.
A resource the connector has no place it can ask about (no space row, no legacy chat) is a warning finding, never left out.
Sentences are rendered in the creator's language at the time of the run; the state words are stable.

connector.status_changed — the installation's own verdict, fired by the verification inside the run when the state moved.
Connector events overview — back to family overview.