Event reference

Every event Cheetah dispatches shares one envelope and carries an event-specific data object. Delivery and retries: webhooks. When each event fires: program lifecycle events.

The envelope#

Both kiosk_serial_number and service_version identify the sender, not the run, so they appear on every event — including WebhookTest. Use them to attribute events when several Cheetah units post to one endpoint.

schema_version#

All events currently ship at schema_version: 3. The schema is versioned independently of the HTTP API and of the transport — see the versioning policy. Two rules for consumers:

• Ignore unknown fields. New fields may be added without bumping schema_version — to the envelope as well as to a data object. A field you don't recognize is not an error.
• Pin to a version you've tested. A breaking change ships under a higher schema_version; existing subscribers keep receiving the prior shape during an announced transition window.

3 replaced the internal canonical_units flag on each QC check with a receiver-facing unit, added nominal, and added unit_system to ProgramCompleted data. That was a breaking per-check change from 2; see ProgramCompleted.

Common data fields#

These fields appear in the data object of all four lifecycle events:

The sections below document only the fields each event adds to these, but each example payload is complete.

ProgramStarted#

Fires when a program run begins executing on a part. Adds no fields beyond the common set; completed_at is null.

{
  "schema_version": 3,
  "event_name": "ProgramStarted",
  "event_id": "8f3a1c20-2b7e-4f1a-9c44-6d0b1e2f3a45",
  "timestamp": 1714291200000,
  "delivery_attempt": 1,
  "kiosk_serial_number": "CHEETAH-KIOSK-0042",
  "service_version": "1.6.0",
  "data": {
    "run_id": "1f5b9d8e-7a32-4c11-8e90-2a4b6c8d0e12",
    "program_id": "a2c4e6f8-1234-5678-9abc-def012345678",
    "program_name": "Bracket QC",
    "robot_id": "arm-1",
    "serial_number": "SN-4471",
    "revision": 2,
    "started_at": "2026-04-28T13:00:00+00:00",
    "completed_at": null
  }
}

ProgramCompleted#

Fires when a program run finishes and the QC outcome has been computed. This is the event that carries the inspection result.

Each entry in qc_checks:

Changed in schema_version: 3. Checks previously carried canonical_units ("mm" | "unspecified"), an internal flag, and values were always mm. They now carry unit, and length values are converted to inches when unit_system is "imperial". Read unit — never assume mm.

Each entry in files (FileMetadata):

The files array is an additive field — it was added without a schema_version bump. See Pull run files for full details on the consolidated file-access endpoints.

{
  "schema_version": 3,
  "event_name": "ProgramCompleted",
  "event_id": "7d2e9a14-3c5b-4a82-b1f6-90c3e5a7b9d1",
  "timestamp": 1714291242000,
  "delivery_attempt": 1,
  "kiosk_serial_number": "CHEETAH-KIOSK-0042",
  "service_version": "1.6.0",
  "data": {
    "run_id": "1f5b9d8e-7a32-4c11-8e90-2a4b6c8d0e12",
    "program_id": "a2c4e6f8-1234-5678-9abc-def012345678",
    "program_name": "Bracket QC",
    "robot_id": "arm-1",
    "serial_number": "SN-4471",
    "revision": 2,
    "started_at": "2026-04-28T13:00:00+00:00",
    "completed_at": "2026-04-28T13:00:42+00:00",
    "passed": true,
    "qc_checks": [
      {
        "name": "flatness",
        "status": "pass",
        "value": 0.04,
        "nominal": 0.0,
        "threshold": 0.10,
        "delta": 0.04,
        "unit": "mm"
      },
      {
        "name": "weld_seam_continuity",
        "status": "pass",
        "value": 1.0,
        "nominal": 1.0,
        "threshold": 0.95,
        "delta": 0.05,
        "unit": null
      }
    ],
    "files": [
      {
        "name": "cl_sweep_step_1.csv",
        "type": "measurement",
        "content_type": "text/csv",
        "size_in_bytes": 14832,
        "description": null,
        "href": "/runs/1f5b9d8e-7a32-4c11-8e90-2a4b6c8d0e12/files/cl_sweep_step_1.csv",
        "step_index": 1,
        "frame_id": null,
        "created_at": "2026-04-28T13:00:40+00:00",
        "updated_at": "2026-04-28T13:00:40+00:00",
        "deleted_at": null
      }
    ],
    "defects": [],
    "unit_system": "metric"
  }
}

ProgramFailed#

Fires when a program run stops on a step error before producing an outcome.

{
  "schema_version": 3,
  "event_name": "ProgramFailed",
  "event_id": "b4f1a6c8-5d20-4e3a-9f12-7c8e0a2b4d6f",
  "timestamp": 1714291230000,
  "delivery_attempt": 1,
  "kiosk_serial_number": "CHEETAH-KIOSK-0042",
  "service_version": "1.6.0",
  "data": {
    "run_id": "1f5b9d8e-7a32-4c11-8e90-2a4b6c8d0e12",
    "program_id": "a2c4e6f8-1234-5678-9abc-def012345678",
    "program_name": "Bracket QC",
    "robot_id": "arm-1",
    "serial_number": "SN-4471",
    "revision": 2,
    "started_at": "2026-04-28T13:00:00+00:00",
    "completed_at": "2026-04-28T13:00:18+00:00",
    "error_message": "scanner returned no point cloud for step 3",
    "error_step_index": 3
  }
}

ProgramCancelled#

Fires when an operator cancels a program run. No outcome is produced.

{
  "schema_version": 3,
  "event_name": "ProgramCancelled",
  "event_id": "e2a7c4b9-6f31-4d8a-a0e5-3b9d1f7c2e84",
  "timestamp": 1714291215000,
  "delivery_attempt": 1,
  "kiosk_serial_number": "CHEETAH-KIOSK-0042",
  "service_version": "1.6.0",
  "data": {
    "run_id": "1f5b9d8e-7a32-4c11-8e90-2a4b6c8d0e12",
    "program_id": "a2c4e6f8-1234-5678-9abc-def012345678",
    "program_name": "Bracket QC",
    "robot_id": "arm-1",
    "serial_number": "SN-4471",
    "revision": 2,
    "started_at": "2026-04-28T13:00:00+00:00",
    "completed_at": "2026-04-28T13:00:09+00:00",
    "error_message": "cancelled by operator"
  }
}

WebhookTest#

Not a lifecycle event. The Test action on a webhook in cheetah-ui sends this synthetic event so you can confirm an endpoint receives, verifies, and acknowledges a delivery before any real program run depends on it. It has no associated program run, and its data is a fixed message.

{
  "schema_version": 3,
  "event_name": "WebhookTest",
  "event_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "timestamp": 1714291200000,
  "delivery_attempt": 1,
  "kiosk_serial_number": "CHEETAH-KIOSK-0042",
  "service_version": "1.6.0",
  "data": {
    "message": "This is a test event from cheetah-service."
  }
}

A receiver written against the real events should treat WebhookTest as a no-op — return 2xx and don't try to write it to your system of record.