Operation Events

Operation events fire when Cobalt performs an automated action inside the EHR system. They confirm the success or failure of operations Cobalt initiated on your behalf — creating appointments, adding patient insurance, uploading notes, creating tasks, and so on.

Some events listed here (appointment.created, appointment.updated, patient.updated) also fire from EHR sync when staff make changes directly in the EHR. See Sync Events for those.

Payload Envelope

Every operation event uses this envelope:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "7b4e9f21-c83a-4d56-b107-332f8a1c0e94",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "appointment.created",
  "job_id": "12345",
  "action": "cobalt_operation",
  "data": {
    // Event-specific payload
  }
}

Field	Type	Description
`id`	string	Unique identifier for this event
`access_token_reference_id`	string	Your reference ID associated with this webhook
`access_token_id`	string	UUID of the specific connection (link access token) that generated this event
`object`	string	Always `"event"`
`created`	string	ISO 8601 timestamp when the event was created
`type`	string	The event type
`job_id`	string	API log ID for tracking the operation
`action`	string	Always `"cobalt_operation"` on operation events. The matching Sync Events carry `"ehr_sync"`, so shared event types like `patient.updated` can be told apart by this field.
`data`	object	Event-specific data payload

This envelope (with object: "event" and created) applies to operation, sync, and on-demand live-fetch events (appointment.live_fetch_completed, availability.live_fetch_completed, patient.live_fetch_completed) alike. Live-fetch events carry action: "sync" and additionally include a timestamp field, a legacy alias of created retained for backward compatibility; prefer created. See Receiving Webhooks for details.

Structured Error Codes

Operation failure events (appointment.failed, patient.failed, etc.) include structured error codes so you can handle different failure scenarios programmatically:

Machine-readable error codes — parse errors programmatically instead of string matching
Context-aware descriptions — error messages include specific details (MRN, provider names)
Backward compatibility — the legacy failure_reason field is still included

Error Response Structure

Failure events include both the legacy failure_reason field and a reasons array:

{
  "type": "appointment.failed",
  "data": {
    "appointment_id": "abc123def456",
    "mrn": "MRN123456",
    "failure_reason": "Patient MRN 'MRN123456' not found. Please update the MRN...",
    "reasons": [
      {
        "code": "PATIENT_NOT_FOUND",
        "description": "Patient MRN 'MRN123456' not found. Please update the MRN using the PATCH /v1/appointments/:id endpoint."
      }
    ]
  }
}

failure_reason (string) — concatenated description for backward compatibility
reasons (array) — structured error objects, each with a machine-readable code and a human-readable description

Handling Errors Programmatically

function handleAppointmentFailed(webhookData) {
  const reasons = webhookData.data.reasons || [];

  for (const reason of reasons) {
    switch (reason.code) {
      case 'PATIENT_NOT_FOUND':
        updatePatientMrn(webhookData.data.mrn);
        break;
      case 'PROVIDER_UNAVAILABLE':
        findAlternativeSlots(webhookData.data.appointment_id);
        break;
      case 'INVALID_VISIT_TYPE':
        mapVisitType(webhookData.data.appointment_id);
        break;
      default:
        alertSupport(reason);
    }
  }
}

Appointment Events

appointment.created

Triggered when Cobalt successfully creates an appointment in the EHR.Payload Example:

{
  "id": "759df7ac-2688-44a9-926c-58d36376b412",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T16:05:48.929Z",
  "type": "appointment.created",
  "job_id": "12345",
  "data": {
    "appointment_id": "c5c0e613fc7d68a1c01ef4160483a0b6",
    "emr_appointment_id": "482129",
    "patient_mrn": "44235"
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s unique identifier for the appointment (dashless UUID)
`emr_appointment_id`	string	The EHR’s native appointment ID
`patient_mrn`	string	Patient’s Medical Record Number

Some EMRs include additional fields on this event.

appointment.updated

Triggered when Cobalt successfully updates an appointment in the EHR.Payload Example:

{
  "id": "508c368e7de13b40f9397eec966d0329",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T08:50:42.491-07:00",
  "type": "appointment.updated",
  "job_id": "12345",
  "data": {
    "id": "0551c88b2249945151f967525ee3f7b4",
    "ehr_appointment_id": "482129",
    "patient_mrn": "804",
    "patient_name": "John Doe",
    "datetime": "2025-07-28T16:00:00.000Z",
    "duration": 20,
    "location": "2",
    "status": "2",
    "provider_name": "Dr. Michael Denenberg",
    "appointment_type": "FOLLOW-UP",
    "appointment_mode": "office",
    "updated_fields": {
      "status": "2"
    }
  }
}

Data Fields:

Field	Type	Description
`id`	string	Cobalt’s unique identifier for the appointment
`ehr_appointment_id`	string	The EHR’s native appointment ID
`patient_mrn`	string	Patient’s Medical Record Number
`patient_name`	string	Patient’s full name
`datetime`	string	Appointment date and time (ISO 8601)
`duration`	number	Appointment duration in minutes
`location`	string	Appointment location/room
`status`	string	Appointment status code
`provider_name`	string	Provider’s name
`appointment_type`	string	Type of appointment
`appointment_mode`	string	Mode (e.g., “office”, “telehealth”)
`updated_fields`	object	Fields that changed in this update

appointment.failed

Triggered when Cobalt fails to create an appointment in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "appointment.failed",
  "job_id": "12345",
  "data": {
    "appointment_id": "abc123def456",
    "mrn": "MRN123456",
    "failure_reason": "Patient MRN 'MRN123456' not found. Please update the MRN using the PATCH /v1/appointments/:id endpoint.",
    "reasons": [
      {
        "code": "PATIENT_NOT_FOUND",
        "description": "Patient MRN 'MRN123456' not found. Please update the MRN using the PATCH /v1/appointments/:id endpoint."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s identifier for the failed appointment
`mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

PATIENT_NOT_FOUND — Patient not found in EHR
PROVIDER_NOT_FOUND — Provider not found or invalid
INVALID_VISIT_TYPE — Visit type not configured in EHR
LOCATION_NOT_FOUND — Location/facility not found
TIME_SLOT_UNAVAILABLE — Requested time slot is not available
PROVIDER_UNAVAILABLE — Provider unavailable at requested time
DOUBLE_BOOKING_CONFLICT — Provider’s schedule has a conflicting visit or block at the requested time (only returned when prevent_double_booking: "true" was set on the appointment)
INVALID_COMPLAINT_TYPE — Chief complaint type not found
EHR_RATE_LIMITED — The EHR rate limited requests; retry in a few moments
EXPIRED — The request’s expires_at time passed before the appointment could be saved
TERMINAL_FAILURE — Unspecified terminal failure

appointment.update_failed

Triggered when Cobalt fails to update an existing appointment in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "appointment.update_failed",
  "job_id": "12345",
  "data": {
    "appointment_id": "abc123def456",
    "mrn": "MRN123456",
    "failure_reason": "Appointment not found in EHR. The appointment may have been deleted or moved.",
    "reasons": [
      {
        "code": "APPOINTMENT_NOT_FOUND",
        "description": "Appointment not found in EHR. The appointment may have been deleted or moved."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s identifier for the appointment
`mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

APPOINTMENT_NOT_FOUND — Appointment not found in EHR
SECTION_LOCKED — Appointment section is locked
INVALID_STATUS — Invalid status transition
UPDATE_BLOCKED — Update blocked by EHR rules
CLAIMS_ASSOCIATED — Claims exist, update not allowed
UPDATE_VERIFICATION_FAILED — Update verification failed
TERMINAL_FAILURE — Unspecified terminal failure

Patient Events

patient.created

Triggered when Cobalt successfully creates a patient in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "patient.created",
  "job_id": "12345",
  "action": "cobalt_operation",
  "data": {
    "patient_id": "xyz789uvw012",
    "mrn": "MRN123456",
    "eligibility_information": [
      {
        "insurance_name": "Aetna",
        "status": "Active"
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`patient_id`	string	Cobalt’s unique identifier for the patient
`mrn`	string	Patient’s EHR-native identifier (Medical Record Number)
`eligibility_information`	array	Present only when the create was submitted with `check_eligibility=true`. Availability depends on EHR support.

To retrieve the full patient record (including ehr_id and demographics), call GET /v1/patients filtered by the returned mrn.

patient.failed

Triggered when Cobalt fails to create a patient in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "patient.failed",
  "job_id": "12345",
  "data": {
    "patient_id": "xyz789uvw012",
    "failure_reason": "Patient already exists with MRN 'MRN789456'.",
    "reasons": [
      {
        "code": "DUPLICATE_PATIENT",
        "description": "Patient already exists with MRN 'MRN789456'. Please update the patient information using the PATCH /v1/patients/:id endpoint or search using GET /v1/patients."
      }
    ],
    "existing_mrn": "MRN789456"
  }
}

Data Fields:

Field	Type	Description
`patient_id`	string	Cobalt’s identifier for the failed patient creation
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`
`existing_mrn`	string	MRN of existing patient (for duplicate errors)

Common Error Codes:

DUPLICATE_PATIENT — Patient already exists with same name/DOB
INVALID_DATE_OF_BIRTH — Date of birth format is invalid
REQUIRED_FIELD_MISSING — Required demographic field missing
INSURANCE_NOT_FOUND — Insurance company not found in EHR
INVALID_INSURANCE_POLICY_TYPE — Insurance policy type invalid
PCP_PROVIDER_NOT_FOUND — Primary care provider not found
REFERRING_PROVIDER_NOT_FOUND — Referring provider not found
PHARMACY_NOT_FOUND — Pharmacy not found in EHR
PERMISSION_DENIED — User lacks permission to create patients
EHR_RATE_LIMITED — The EHR rate limited requests; retry in a few moments
TERMINAL_FAILURE — Unspecified terminal failure

patient.updated

Triggered when Cobalt applies an update to an existing patient in your EHR. Contact/address fields and provider fields are applied independently, so an update can succeed in part. failed_fields and message are present only when some requested fields could not be applied; a fully successful update omits them.Payload Example (partial update):

{
  "id": "550e8400-e29b-41d4-a716-446655440011",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "patient.updated",
  "job_id": "12345",
  "data": {
    "patient_id": "xyz789uvw012",
    "mrn": "MRN123456",
    "updated_fields": ["cell_phone"],
    "failed_fields": [
      {
        "field": "referred_to_provider_id",
        "reason": "eClinicalWorks blocked this change (HTTP 403). This is typically a Workers' Comp or not-fully-registered patient, for which provider and billing fields cannot be modified via the API until the record is fully registered in the EHR."
      }
    ],
    "message": "Updated cell_phone. Could not update referred_to_provider_id (...)."
  }
}

Data Fields:

Field	Type	Description
`patient_id`	string	Cobalt’s unique identifier for the patient
`mrn`	string	Patient’s Medical Record Number
`updated_fields`	array	Fields that were successfully applied to the EHR
`failed_fields`	array	Present only on a partial update. Objects with `field` and a human-readable `reason` for each field that could not be applied
`message`	string	Present only on a partial update. Human-readable summary of what was and was not applied

patient.update_failed

Triggered when Cobalt could not apply any of the requested fields to an existing patient (for example, the EHR rejected every change). When at least one field is applied, a patient.updated event carrying failed_fields is sent instead.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440012",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "patient.update_failed",
  "job_id": "12345",
  "data": {
    "patient_id": "xyz789uvw012",
    "mrn": "MRN123456",
    "message": "eClinicalWorks blocked this change (HTTP 403). This is typically a Workers' Comp or not-fully-registered patient, for which provider and billing fields cannot be modified via the API until the record is fully registered in the EHR.",
    "sync_parameters": {
      "referred_to_provider_id": "17832387"
    }
  }
}

Data Fields:

Field	Type	Description
`patient_id`	string	Cobalt’s identifier for the patient
`mrn`	string	Patient’s Medical Record Number
`message`	string	Human-readable reason the update could not be applied
`sync_parameters`	object	The update fields that were attempted

patient.insurance.added

Triggered when Cobalt successfully adds insurance information for a patient.Payload Example:

{
  "id": "evt_abc123def456",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.added",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "plan_begin_date": "2025-01-01",
    "plan_end_date": null,
    "copayment": 25,
    "priority": 1,
    "relationship_to_subscriber": "self",
    "emr_insurance_id": "51638"
  }
}

Data Fields:

Field	Type	Description
`patient_insurance_id`	string	Cobalt’s unique identifier for the insurance record
`patient_mrn`	string	Patient’s Medical Record Number
`member_id`	string	Insurance member / subscriber number (as provided)
`group_id`	string	Insurance group ID
`plan_begin_date`	string	Insurance plan start date (YYYY-MM-DD)
`plan_end_date`	string \| null	Coverage end date (YYYY-MM-DD), null for open-ended coverage
`copayment`	number	Copayment amount
`priority`	number	Insurance priority / sequence
`relationship_to_subscriber`	string \| null	Relationship to the subscriber
`emr_insurance_id`	string \| null	EMR-native insurance record ID

audit_trail is present in the success payload for some EMRs and absent for others, so the payload above may carry more or fewer fields than your integration returns.

patient.insurance.updated

Triggered when Cobalt successfully updates an existing insurance record for a patient.Payload Example:

{
  "id": "evt_abc123def456",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.updated",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "plan_begin_date": "2025-01-01",
    "plan_end_date": "2026-12-31",
    "copayment": 25,
    "priority": 1,
    "relationship_to_subscriber": "spouse",
    "emr_insurance_id": "51638"
  }
}

Data Fields:

Field	Type	Description
`patient_insurance_id`	string	Cobalt’s unique identifier for the insurance update record
`patient_mrn`	string	Patient’s Medical Record Number
`member_id`	string	Effective insurance member / subscriber number after the update
`group_id`	string	Effective insurance group ID after the update
`plan_begin_date`	string	Effective insurance plan start date (YYYY-MM-DD)
`plan_end_date`	string \| null	Effective coverage end date (YYYY-MM-DD), null for open-ended coverage
`copayment`	number	Effective copayment amount
`priority`	number	Insurance priority / sequence
`relationship_to_subscriber`	string \| null	Effective relationship to the subscriber
`emr_insurance_id`	string \| null	EMR-native insurance record ID

patient.insurance.failed

Triggered when Cobalt fails to add or update insurance information for a patient.Payload Example:

{
  "id": "evt_xyz789abc123",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.failed",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "failure_reason": "Patient not found in EMR system"
  }
}

Data Fields:

Field	Type	Description
`patient_insurance_id`	string	Cobalt’s identifier for the insurance record
`patient_mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Human-readable explanation of why the insurance add or update failed

Task Events

task.created

Triggered when Cobalt successfully creates a task in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440011",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "task.created",
  "job_id": "12345",
  "data": {
    "task_id": "task123def456",
    "emr_task_id": "EMR-TASK-789",
    "subject": "Follow up with patient",
    "description": "Call patient regarding lab results",
    "assignee_user_id": "user-456",
    "patient_mrn": "MRN123456"
  }
}

Data Fields:

Field	Type	Description
`task_id`	string	Cobalt’s unique identifier for the task
`emr_task_id`	string	The EHR’s native task ID
`subject`	string	Task subject/title
`description`	string	Detailed task description
`assignee_user_id`	string	ID of the user assigned to the task
`patient_mrn`	string	Patient’s Medical Record Number (if applicable)

task.failed

Triggered when Cobalt fails to create a task in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440012",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "task.failed",
  "job_id": "12345",
  "data": {
    "task_id": "task123def456",
    "failure_reason": "Patient MRN 'MRN123456' not found.",
    "reasons": [
      {
        "code": "PATIENT_NOT_FOUND",
        "description": "Patient MRN 'MRN123456' not found. Please update the patient MRN using the PATCH /v1/tasks/:id endpoint."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`task_id`	string	Cobalt’s identifier for the failed task
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

PATIENT_NOT_FOUND — Patient MRN not found in EHR
ASSIGNEE_NOT_FOUND — Assigned user not found in EHR
INVALID_TASK_DATA — Task data validation failed
PERMISSION_DENIED — User lacks permission to create tasks
TERMINAL_FAILURE — Unspecified terminal failure

Codes Events

codes.added

Triggered when Cobalt finishes adding ICD-10 diagnosis codes to an encounter. icd reports which codes were applied versus skipped as duplicates, not matched in the EMR catalog, or rejected as invalid for the encounter date.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440021",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "codes.added",
  "job_id": "12345",
  "data": {
    "appointment_id": "APPT-12345",
    "operation": "add",
    "icd": {
      "added": ["E11.9", "I10"],
      "skipped": [],
      "unmatched": [],
      "invalid": []
    }
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	The appointment whose encounter was updated
`operation`	string	Always `add`
`icd.added`	string[]	Codes newly added to the encounter
`icd.skipped`	string[]	Codes already present (deduplicated)
`icd.unmatched`	string[]	Codes not found in the EMR catalog
`icd.invalid`	string[]	Codes the EMR rejected as invalid for the encounter date

codes.removed

Triggered when Cobalt finishes removing ICD-10 diagnosis codes from an encounter. not_found lists codes that were not on the encounter.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440022",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "codes.removed",
  "job_id": "12346",
  "data": {
    "appointment_id": "APPT-12345",
    "operation": "remove",
    "icd": {
      "removed": ["I10"],
      "not_found": []
    }
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	The appointment whose encounter was updated
`operation`	string	Always `remove`
`icd.removed`	string[]	Codes removed from the encounter
`icd.not_found`	string[]	Requested codes that were not on the encounter

codes.failed

Triggered when a codes add or remove operation terminally fails.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440023",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "codes.failed",
  "job_id": "12345",
  "data": {
    "appointment_id": "APPT-12345",
    "operation": "add",
    "status": "failed",
    "failure_reason": "eClinicalWorks rejected the diagnosis-code change.",
    "reasons": [
      {
        "code": "ECW_REJECTED_CHANGE",
        "description": "eClinicalWorks rejected the diagnosis-code change."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	The appointment the operation targeted
`operation`	string	`add` or `remove`
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

ECW_REJECTED_CHANGE — The EMR rejected the diagnosis-code change
EHR_RATE_LIMITED — The EHR rate limited requests; retry in a few moments
UPSTREAM_TEMPORARILY_UNAVAILABLE — The EMR was temporarily unavailable; the operation is retried automatically and this only fires if retries are exhausted
UNKNOWN_ERROR — Unspecified terminal failure

Note Events

note.uploaded

Triggered when Cobalt successfully uploads a clinical note to your EHR system.The status field distinguishes a clean upload from a partial success, where the note body was written but one or more diagnosis (ICD) or procedure (CPT) codes could not be matched in the EHR. When codes are present, they are reported under icd_codes and cpt_codes, each split into matched and unmatched (and, for ICD, skipped).Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440013",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "note.uploaded",
  "job_id": "12345",
  "data": {
    "appointment_id": "abc123def456",
    "mrn": "MRN123456",
    "timezone": "America/New_York",
    "status": "partial_success",
    "icd_codes": {
      "matched": [
        { "code": "E11.9", "name": "Type 2 diabetes mellitus without complications" }
      ],
      "unmatched": [
        { "code": "Z00.00", "reason": "Code not found in EHR system" }
      ]
    },
    "cpt_codes": {
      "matched": [
        { "code": "99213", "name": "Office/outpatient visit, established patient" }
      ],
      "unmatched": []
    }
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s appointment identifier
`mrn`	string	Patient’s Medical Record Number
`timezone`	string	Timezone for the appointment
`status`	string	`succeeded` (all codes matched, or none provided) or `partial_success` (note uploaded but some codes did not match)
`icd_codes`	object	Present when ICD codes were provided. Contains `matched`, `unmatched`, and optionally `skipped` arrays
`cpt_codes`	object	Present when CPT codes were provided. Contains `matched` and `unmatched` arrays

Because the note body is written even when a code fails to match, unmatched codes are reported on note.uploaded (with status: "partial_success") rather than note.failed. Check status and the unmatched arrays if you need to reconcile coding.

note.failed

Triggered when Cobalt fails to upload a clinical note to your EHR system. This fires only after retries are exhausted.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "note.failed",
  "job_id": "12345",
  "data": {
    "appointment_id": "abc123def456",
    "mrn": "MRN123456",
    "status": "failed",
    "failure_reason": "Text contains \"]]>\" which cannot be used in CDATA blocks. Please remove this sequence from the note text.",
    "reasons": [
      {
        "code": "UNSUPPORTED_CHARACTERS",
        "description": "Text contains \"]]>\" which cannot be used in CDATA blocks. Please remove this sequence from the note text."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s appointment identifier
`mrn`	string	Patient’s Medical Record Number
`status`	string	Always `failed`
`failure_reason`	string	Human-readable error message (retained for backward compatibility)
`reasons`	array	Structured error objects, each with a machine-readable `code` and a human-readable `description`

Error Codes:

UNSUPPORTED_CHARACTERS — The note text contains characters the EHR cannot accept
MAX_ATTEMPTS_EXCEEDED — Note creation failed after all retry attempts
UNKNOWN_ERROR — An unexpected error occurred

Document Events

document.uploaded

Triggered when Cobalt successfully uploads a document to your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "document.uploaded",
  "data": {
    "document_id": "doc123456",
    "patient_mrn": "MRN123456",
    "folder_name": "Lab Results"
  }
}

Data Fields:

Field	Type	Description
`document_id`	string	Cobalt’s unique identifier for the document
`patient_mrn`	string	Patient’s Medical Record Number
`folder_name`	string	EHR folder/category where document was uploaded

document.failed

Triggered when Cobalt fails to upload a document to your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "document.failed",
  "data": {
    "document_id": "doc123456",
    "patient_mrn": "MRN123456",
    "folder_name": "Lab Results",
    "reasons": [
      {
        "code": "PATIENT_NOT_FOUND",
        "description": "Failed to find a patient with the given mrn."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`document_id`	string	Cobalt’s identifier for the document
`patient_mrn`	string	Patient’s Medical Record Number
`folder_name`	string	Target EHR folder/category
`reasons`	array	List of error objects with `code` and `description`

Common Error Codes:

PATIENT_NOT_FOUND — Patient not found in EHR
DOCUMENT_CLASS_NOT_FOUND — Document folder/category not found
INVALID_DOCUMENT_CONTENT — Document content is invalid
DOCUMENT_UPLOAD_FAILED — Upload failed for unspecified reason
UNKNOWN_ERROR — Unexpected error occurred

document.upload_failed

Triggered when Cobalt fails to upload a document to the EHR.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "document.upload_failed",
  "data": {
    "document_id": "doc123456",
    "patient_mrn": "MRN123456",
    "folder_name": "Lab Results",
    "failure_reason": "Document class 'Lab Results' not found in eClinicalWorks. Please verify the folder name.",
    "reasons": [
      {
        "code": "DOCUMENT_CLASS_NOT_FOUND",
        "description": "Document class 'Lab Results' not found in eClinicalWorks. Please verify the folder name."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`document_id`	string	Cobalt’s identifier for the document
`patient_mrn`	string	Patient’s Medical Record Number
`folder_name`	string	Target EHR folder/category
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

PATIENT_NOT_FOUND — Patient not found in EHR
DOCUMENT_CLASS_NOT_FOUND — Document folder/category not found
UNKNOWN_ERROR — Unexpected error occurred during upload

Message Events

message.created

Triggered when Cobalt successfully creates a message in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440007",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "message.created",
  "job_id": "12345",
  "data": {
    "message_id": "msg123def456",
    "provider_id": "provider-789",
    "subject": "Patient Follow-up"
  }
}

Data Fields:

Field	Type	Description
`message_id`	string	Cobalt’s unique identifier for the message
`provider_id`	string	ID of the provider who received the message
`subject`	string	Message subject line

message.failed

Triggered when Cobalt fails to create a message in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440008",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "message.failed",
  "job_id": "12345",
  "data": {
    "message_id": "msg123def456",
    "provider_id": "provider-789",
    "failure_reason": "Failed to send message. Please try again or contact support if the issue persists.",
    "reasons": [
      {
        "code": "MESSAGE_SEND_FAILED",
        "description": "Failed to send message. Please try again or contact support if the issue persists."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`message_id`	string	Cobalt’s identifier for the message
`provider_id`	string	ID of the target provider
`failure_reason`	string	Legacy human-readable error message
`reasons`	array	Structured error objects with `code` and `description`

Common Error Codes:

MESSAGE_SEND_FAILED — Message failed to send
PROVIDER_NOT_FOUND — Provider not found in EHR
INVALID_MESSAGE_CONTENT — Message content validation failed
MESSAGE_TOO_LONG — Message exceeds maximum length
TERMINAL_FAILURE — Unspecified terminal failure

Telephone Encounter Events

telephone_encounter.created

Triggered when Cobalt successfully creates a telephone encounter in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440020",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "telephone_encounter.created",
  "job_id": "12345",
  "data": {
    "telephone_encounter_id": "abc123def456",
    "emr_encounter_id": "EMR-ENC-789",
    "patient_mrn": "MRN123456",
    "provider_id": "provider-456",
    "location_id": "location-789",
    "assigned_to_id": "user-101",
    "reason": "Medication refill request",
    "refill_medication_name": "Lisinopril 10mg"
  }
}

Data Fields:

Field	Type	Description
`telephone_encounter_id`	string	Cobalt’s unique identifier for the telephone encounter
`emr_encounter_id`	string	The EHR’s native encounter ID
`patient_mrn`	string	Patient’s Medical Record Number
`provider_id`	string	EHR provider ID
`location_id`	string	EHR location ID
`assigned_to_id`	string	EHR user ID the encounter is assigned to
`reason`	string \| null	Reason for the telephone encounter
`refill_medication_name`	string	Medication name (only present when a refill was requested and added successfully)

telephone_encounter.created_partial

Triggered when Cobalt creates a telephone encounter successfully but a requested medication refill could not be added.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440021",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "telephone_encounter.created_partial",
  "job_id": "12345",
  "data": {
    "telephone_encounter_id": "abc123def456",
    "emr_encounter_id": "EMR-ENC-789",
    "patient_mrn": "MRN123456",
    "provider_id": "provider-456",
    "location_id": "location-789",
    "assigned_to_id": "user-101",
    "reason": "Medication refill request",
    "refill_medication_name": "Lisinopril 10mg",
    "refill_failure_reason": "Medication not found in patient's active medication list"
  }
}

Data Fields:

Field	Type	Description
`telephone_encounter_id`	string	Cobalt’s unique identifier for the telephone encounter
`emr_encounter_id`	string	The EHR’s native encounter ID
`patient_mrn`	string	Patient’s Medical Record Number
`provider_id`	string	EHR provider ID
`location_id`	string	EHR location ID
`assigned_to_id`	string	EHR user ID the encounter is assigned to
`reason`	string \| null	Reason for the telephone encounter
`refill_medication_name`	string	Requested medication name
`refill_failure_reason`	string	Why the medication refill could not be added

The encounter itself was created successfully — only the medication refill portion failed. Follow up manually to add the refill or notify the requester.

telephone_encounter.failed

Triggered when Cobalt fails to create a telephone encounter in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440022",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "telephone_encounter.failed",
  "job_id": "12345",
  "data": {
    "telephone_encounter_id": "abc123def456",
    "patient_mrn": "MRN123456",
    "refill_medication_name": "Lisinopril 10mg",
    "failure_reason": "Unable to create telephone encounter: Provider license has expired in eCW. Please update the provider license and try again."
  }
}

Data Fields:

Field	Type	Description
`telephone_encounter_id`	string	Cobalt’s identifier for the failed telephone encounter
`patient_mrn`	string \| null	Patient’s Medical Record Number
`refill_medication_name`	string \| null	Requested medication name (if a refill was requested)
`failure_reason`	string	Detailed explanation of why the telephone encounter creation failed

telephone_encounter_action.created

Triggered when Cobalt successfully adds an action (note/update) to an existing telephone encounter.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440023",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "telephone_encounter_action.created",
  "job_id": "12345",
  "data": {
    "action_id": "act123def456",
    "emr_appointment_id": "EMR-ENC-789",
    "text": "Spoke with patient — refill approved by Dr. Smith. Patient instructed to pick up at preferred pharmacy."
  }
}

Data Fields:

Field	Type	Description
`action_id`	string	Cobalt’s unique identifier for the action
`emr_appointment_id`	string	The EHR’s encounter/appointment ID the action was added to
`text`	string	The action text/note that was added

telephone_encounter_action.failed

Triggered when Cobalt fails to add an action to a telephone encounter.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440024",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "telephone_encounter_action.failed",
  "job_id": "12345",
  "data": {
    "action_id": "act123def456",
    "emr_appointment_id": "EMR-ENC-789",
    "failure_reason": "ECW API returned non-success status: failure. Error: Encounter is locked"
  }
}

Data Fields:

Field	Type	Description
`action_id`	string	Cobalt’s identifier for the action
`emr_appointment_id`	string \| null	The EHR’s encounter/appointment ID the action targeted
`failure_reason`	string	Detailed explanation of why the action failed

Order Events

order_catalog.searched

Triggered when a catalog search started via POST /v1/orders/catalog/fetch completes. The items array holds one page of orderable catalog entries; use their item_id values to create an order.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440021",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "order_catalog.searched",
  "job_id": "12345",
  "data": {
    "type": "lab",
    "page": 1,
    "has_more": true,
    "items": [
      { "item_id": "80048", "name": "Comprehensive Metabolic Panel", "billable": true },
      { "item_id": "82947", "name": "Glucose, Serum", "billable": true }
    ]
  }
}

Data Fields:

Field	Type	Description
`type`	string	Catalog searched: `lab`, `imaging`, or `procedure`
`page`	integer	Page number of these results
`has_more`	boolean	Whether more pages are available
`items`	array	Catalog entries, each with `item_id`, `name`, and `billable`

order.created

Triggered when Cobalt successfully creates an order in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440022",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "order.created",
  "job_id": "12345",
  "data": {
    "emr_order_id": "998877",
    "emr_encounter_id": "445566",
    "patient_mrn": "MRN123456"
  }
}

Data Fields:

Field	Type	Description
`emr_order_id`	string	The EHR’s native order ID
`emr_encounter_id`	string	The EHR’s encounter/appointment ID the order belongs to
`patient_mrn`	string	Patient’s Medical Record Number

order.create_failed

Triggered when Cobalt fails to create an order in your EHR system.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440023",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "order.create_failed",
  "job_id": "12345",
  "data": {
    "patient_mrn": "MRN123456",
    "failure_reason": "Order create failed after multiple attempts. Please try again later or contact support."
  }
}

Data Fields:

Field	Type	Description
`patient_mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Human-readable explanation of the failure

order.updated

Triggered when Cobalt successfully updates an order via PATCH /v1/orders/:id.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440024",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "order.updated",
  "job_id": "12345",
  "data": {
    "emr_order_id": "998877",
    "emr_encounter_id": "445566",
    "patient_mrn": "MRN123456"
  }
}

Data Fields:

Field	Type	Description
`emr_order_id`	string	The EHR’s native order ID
`emr_encounter_id`	string	The EHR’s encounter/appointment ID the order belongs to
`patient_mrn`	string	Patient’s Medical Record Number

order.update_failed

Triggered when Cobalt fails to update an order via PATCH /v1/orders/:id.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440025",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "order.update_failed",
  "job_id": "12345",
  "data": {
    "patient_mrn": "MRN123456",
    "failure_reason": "Order update failed after multiple attempts. Please try again later or contact support."
  }
}

Data Fields:

Field	Type	Description
`patient_mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Human-readable explanation of the failure

lab_result.created

Triggered when Cobalt successfully creates a lab result for an order via POST /v1/orders/:id/results.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440026",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "lab_result.created",
  "job_id": "12345",
  "data": {
    "lab_result_id": "lr_123456",
    "order_id": "ord_123456",
    "emr_order_id": "998877",
    "emr_encounter_id": "445566",
    "patient_mrn": "MRN123456"
  }
}

Data Fields:

Field	Type	Description
`lab_result_id`	string	Cobalt’s unique identifier for the lab result
`order_id`	string	Cobalt’s identifier for the order the result belongs to
`emr_order_id`	string	The EHR’s native order ID
`emr_encounter_id`	string	The EHR’s encounter/appointment ID the order belongs to
`patient_mrn`	string	Patient’s Medical Record Number

lab_result.create_failed

Triggered when Cobalt fails to create a lab result for an order via POST /v1/orders/:id/results.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440027",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "lab_result.create_failed",
  "job_id": "12345",
  "data": {
    "lab_result_id": "lr_123456",
    "order_id": "ord_123456",
    "patient_mrn": "MRN123456",
    "failure_reason": "Lab result creation failed after multiple attempts. Please try again later or contact support."
  }
}

Data Fields:

Field	Type	Description
`lab_result_id`	string	Cobalt’s identifier for the lab result
`order_id`	string	Cobalt’s identifier for the order the result belongs to
`patient_mrn`	string	Patient’s Medical Record Number
`failure_reason`	string	Human-readable explanation of the failure

Test Event

test.event

A test event used to verify webhook delivery and integration setup. Trigger it manually using the Send Test Webhook endpoint (POST /v1/webhook/test).Payload Example:

{
  "id": "test-event-1703172600000",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "test.event",
  "data": {
    "message": "This is a test webhook event",
    "timestamp": "2025-10-21T14:30:00.000Z"
  }
}

Data Fields:

Field	Type	Description
`message`	string	Test message content
`timestamp`	string	When the test event was generated

Triggering a Test Event:

curl -X POST https://api.cobalt.run/v1/webhook/test \
  -H "client_id: YOUR_CLIENT_ID" \
  -H "client_secret: YOUR_CLIENT_SECRET" \
  -H "access_token: YOUR_ACCESS_TOKEN"

The test event is sent to all configured webhook URLs for your client. Use it to verify your endpoint is receiving events, your signature verification logic works, and your event processing pipeline is healthy.

You must have at least one webhook URL configured (POST /v1/webhook) before sending a test event.

Introduction

Guides

Operation Events

Payload Envelope

Structured Error Codes

Error Response Structure

Handling Errors Programmatically

Appointment Events

Patient Events

Task Events

Codes Events

Note Events

Document Events

Message Events

Telephone Encounter Events

Order Events

Test Event

​Payload Envelope

​Structured Error Codes

​Error Response Structure

​Handling Errors Programmatically

​Appointment Events

​Patient Events

​Task Events

​Codes Events

​Note Events

​Document Events

​Message Events

​Telephone Encounter Events

​Order Events

​Test Event

Payload Envelope

Structured Error Codes

Error Response Structure

Handling Errors Programmatically

Appointment Events

Patient Events

Task Events

Codes Events

Note Events

Document Events

Message Events

Telephone Encounter Events

Order Events

Test Event