Operation Events

Operation events fire when Cobalt performs an RPA action inside your 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) 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",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "appointment.created",
  "job_id": "12345",
  "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
`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
`data`	object	Event-specific data payload

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 your EHR via an RPA action.Payload Example:

{
  "id": "759df7ac-2688-44a9-926c-58d36376b412",
  "access_token_reference_id": "clinic_1",
  "object": "event",
  "created": "2025-07-28T16:05:48.929Z",
  "type": "appointment.created",
  "job_id": "12345",
  "data": {
    "appointment_id": "c5c0e613fc7d68a1c01ef4160483a0b6",
    "mrn": "44235",
    "date_time": "2025-07-28T16:00:00.000Z",
    "timezone": "America/New_York",
    "provider_id": "defe69ae-f363-4797-87bd-1c70acb52b21",
    "provider_name": "Dr. Jose Gonzalez",
    "secondary_provider_id": null
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s unique identifier for the appointment
`mrn`	string	Patient’s Medical Record Number
`date_time`	string	Appointment date and time (ISO 8601)
`timezone`	string	Timezone for the appointment
`provider_id`	string	Primary provider’s ID
`provider_name`	string	Primary provider’s name
`secondary_provider_id`	string \| null	Secondary provider’s ID (if applicable)

appointment.updated

Triggered when Cobalt successfully updates an appointment in your EHR via an RPA action.Payload Example:

{
  "id": "508c368e7de13b40f9397eec966d0329",
  "access_token_reference_id": "clinic_1",
  "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",
  "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
INVALID_COMPLAINT_TYPE — Chief complaint type not found
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",
  "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",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "patient.created",
  "job_id": "12345",
  "data": {
    "patient_id": "xyz789uvw012",
    "mrn": "MRN123456",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1985-06-15",
    "sex": "F",
    "email": "jane.smith@example.com",
    "phone": "555-0123"
  }
}

Data Fields:

Field	Type	Description
`patient_id`	string	Cobalt’s unique identifier for the patient
`mrn`	string	Patient’s Medical Record Number
`first_name`	string	Patient’s first name
`last_name`	string	Patient’s last name
`date_of_birth`	string	Patient’s date of birth (YYYY-MM-DD)
`sex`	string	Patient’s sex
`email`	string	Patient’s email address
`phone`	string	Patient’s phone number

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",
  "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
TERMINAL_FAILURE — Unspecified terminal failure

patient.insurance.added

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

{
  "id": "evt_abc123def456",
  "access_token_reference_id": "clinic_1",
  "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",
    "copayment": 25,
    "audit_trail": [
      {
        "field_label": "Insurance Company",
        "before": "",
        "after": "AHMC Health",
        "property": "insurance_company"
      },
      {
        "field_label": "Member ID",
        "before": "",
        "after": "MEM123456789",
        "property": "member_id"
      }
    ]
  }
}

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 ID
`group_id`	string	Insurance group ID
`plan_begin_date`	string	Insurance plan start date (YYYY-MM-DD)
`copayment`	number	Copayment amount
`audit_trail`	array	List of fields modified in the EHR with before/after values

patient.insurance.failed

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

{
  "id": "evt_xyz789abc123",
  "access_token_reference_id": "clinic_1",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.failed",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "error": "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
`error`	string	Human-readable explanation of why the insurance addition 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",
  "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",
  "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

Note Events

note.uploaded

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

{
  "id": "550e8400-e29b-41d4-a716-446655440013",
  "access_token_reference_id": "clinic_1",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "note.uploaded",
  "data": {
    "appointment_id": "abc123def456",
    "patient_mrn": "MRN123456",
    "note_type": "Progress Note",
    "provider_name": "Dr. Sarah Johnson"
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s appointment identifier
`patient_mrn`	string	Patient’s Medical Record Number
`note_type`	string	Type of clinical note uploaded
`provider_name`	string	Name of the provider who authored the note

note.failed

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

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "access_token_reference_id": "clinic_1",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "note.failed",
  "data": {
    "appointment_id": "abc123def456",
    "timezone": "America/New_York",
    "mrn": "MRN123456",
    "reasons": [
      {
        "code": "SECTION_NOT_FOUND",
        "description": "Failed to find the HPI section. Please ensure the note template has the required sections."
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`appointment_id`	string	Cobalt’s appointment identifier
`timezone`	string	Timezone for the appointment
`mrn`	string	Patient’s Medical Record Number
`reasons`	array	List of error objects with `code` and `description`

Common Error Codes:

SECTION_NOT_FOUND — Required note section not found in template
PATIENT_NOT_FOUND — Patient not found in EHR
APPOINTMENT_NOT_FOUND — Appointment not found in EHR
UNKNOWN_ERROR — 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",
  "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",
  "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 eClinicalWorks specifically.Payload Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "access_token_reference_id": "clinic_1",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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

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",
  "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

Payload Envelope

Structured Error Codes

Error Response Structure

Handling Errors Programmatically

Appointment Events

Patient Events

Task Events

Note Events

Document Events

Message Events

Telephone Encounter Events

Test Event

Introduction

Guides

Documentation Index

​Payload Envelope

​Structured Error Codes

​Error Response Structure

​Handling Errors Programmatically

​Appointment Events

​Patient Events

​Task Events

​Note Events

​Document Events

​Message Events

​Telephone Encounter Events

​Test Event

Payload Envelope

Structured Error Codes

Error Response Structure

Handling Errors Programmatically

Appointment Events

Patient Events

Task Events

Note Events

Document Events

Message Events

Telephone Encounter Events

Test Event