Sync Events

Sync events fire when Cobalt detects changes that occurred directly in your EHR system. These keep you informed about activities your staff performed in the EHR itself — appointments scheduled, patient information updated, and statuses changed.

appointment.created and appointment.updated also fire as Operation Events when triggered by an action Cobalt performed. The event types are the same; the trigger differs.

Payload Envelope

Every sync event uses this envelope:

{
  "id": "508c368e7de13b40f9397eec966d0329",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T08:50:42.491-07:00",
  "type": "appointment.updated",
  "action": "ehr_sync",
  "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
`action`	string	Always `"ehr_sync"` on sync events. The matching Operation Events carry `"cobalt_operation"`, 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 sync, operation, 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.

Appointment Events

appointment.created

Triggered when EHR staff create an appointment in your EHR (detected by Cobalt’s sync).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",
  "data": {
    "id": "0551c88b2249945151f967525ee3f7b4",
    "ehr_appointment_id": "482129",
    "patient_mrn": "44235",
    "patient_name": "John Doe",
    "datetime": "2025-07-28T16:00:00.000Z",
    "duration": 20,
    "location": "2",
    "status": "1",
    "provider_ehr_id": "1568",
    "secondary_provider_ehr_id": null,
    "provider_name": "Dr. Jose Gonzalez",
    "provider_npi": "1234567890",
    "appointment_type": "OFFICE VISIT",
    "appointment_mode": "office"
  }
}

Data Fields:The full appointment record is included (same shape as appointment.updated, without updated_fields). Key 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 (EMR facility ID)
`status`	string	Appointment status code
`provider_ehr_id`	string \| null	Primary provider’s EHR ID (for calendar/assignee mapping)
`secondary_provider_ehr_id`	string \| null	Secondary provider’s EHR ID
`provider_name`	string	Primary provider’s name
`provider_npi`	string \| null	Primary provider’s NPI
`appointment_type`	string	Type of appointment
`appointment_mode`	string	Mode (e.g., “office”, “telehealth”)

appointment.updated

Triggered when EHR staff update an appointment in your EHR (detected by Cobalt’s sync).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",
  "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_ehr_id": "1568",
    "secondary_provider_ehr_id": null,
    "provider_name": "Dr. Michael Denenberg",
    "provider_npi": "1234567890",
    "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_ehr_id`	string \| null	Primary provider’s EHR ID (for calendar/assignee mapping)
`secondary_provider_ehr_id`	string \| null	Secondary provider’s EHR ID
`provider_name`	string	Provider’s name
`provider_npi`	string \| null	Primary provider’s NPI
`appointment_type`	string	Type of appointment
`appointment_mode`	string	Mode (e.g., “office”, “telehealth”)
`updated_fields`	object	Fields that changed in this update

appointment.status_updated

Triggered when an appointment’s status changes in your EHR system.Payload Example:

{
  "id": "508c368e7de13b40f9397eec966d0330",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T09:15:22.491-07:00",
  "type": "appointment.status_updated",
  "data": {
    "id": "0551c88b2249945151f967525ee3f7b4",
    "ehr_appointment_id": "482129",
    "patient_mrn": "804",
    "patient_name": "John Doe",
    "datetime": "2025-07-28T16:00:00.000Z",
    "status": "checked-in",
    "previous_status": "scheduled",
    "provider_name": "Dr. Michael Denenberg"
  }
}

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)
`status`	string	New appointment status
`previous_status`	string	Previous appointment status
`provider_name`	string	Provider’s name

Patient Events

Sync patient events carry the full patient object in data (not a subset), so you can update your own system without a follow-up GET /v1/patients. patient.updated additionally includes a changes map describing what changed. Note that sync events use changes ({ old, new } per field), whereas the Operation patient.updated event uses an updated_fields array of field names.

patient.created

Triggered when EHR staff create a new patient in your EHR (detected by Cobalt’s sync).Payload Example:

{
  "id": "508c368e7de13b40f9397eec966d0330",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T10:18:02.491-07:00",
  "type": "patient.created",
  "action": "ehr_sync",
  "data": {
    "id": "65ed04f9d25fca3876f367d9ad94e3c3",
    "mrn": "MRN123456",
    "ehr_id": "123456",
    "first_name": "Jane",
    "last_name": "Smith",
    "middle_name": null,
    "address_street": "123 Main St",
    "address_city": "Springfield",
    "address_state": "IL",
    "address_zip": "62701",
    "phone": "555-123-4567",
    "cell_phone": "555-123-4568",
    "email": "jane.smith@example.com",
    "dob": "1985-06-15",
    "sex": "female",
    "status": "active",
    "insurance_name": "Aetna",
    "insurance_subscriber_number": "ABC123456",
    "pcp_first_name": "John",
    "pcp_last_name": "Doe"
  }
}

Data Fields:The full patient object. Key identifiers:

Field	Type	Description
`id`	string	Cobalt’s unique identifier for the patient (UUID without hyphens)
`mrn`	string	Patient’s Medical Record Number
`ehr_id`	string	The EHR’s native patient identifier

patient.updated

Triggered when EHR staff update patient information in your EHR (detected by Cobalt’s sync).Payload Example:

{
  "id": "508c368e7de13b40f9397eec966d0331",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2025-07-28T10:20:15.491-07:00",
  "type": "patient.updated",
  "action": "ehr_sync",
  "data": {
    "id": "65ed04f9d25fca3876f367d9ad94e3c3",
    "mrn": "MRN123456",
    "ehr_id": "123456",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "555-9999",
    "email": "jane.newemail@example.com",
    "status": "active",
    "changes": {
      "phone": {
        "old": "555-123-4567",
        "new": "555-9999"
      },
      "email": {
        "old": "jane.smith@example.com",
        "new": "jane.newemail@example.com"
      }
    }
  }
}

Data Fields:The full patient object (same shape as patient.created) plus:

Field	Type	Description
`changes`	object	Map of the fields that changed, each with its `old` and `new` value

Fields that can appear in changes: first_name, last_name, middle_name, address_street, address_line2, address_city, address_state, address_zip, phone, cell_phone, home_phone, work_phone, email, dob, sex, status, insurance_name, insurance_subscriber_number, referred_to_provider_id, pcp_first_name, pcp_last_name, medications, problems, vitals.

Insurance changes made directly in the EHR do not currently emit a sync event. Insurance is synced into the patient record, but only Cobalt-initiated add/update calls fire patient.insurance.added / patient.insurance.updated (see Operation Events).

Claim Events

claim.created

Triggered when a new claim is detected in your EHR (detected by Cobalt’s sync).Payload Example:

{
  "id": "759df7ac268844a9926c58d36376b412",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2026-07-13T04:12:08.921Z",
  "type": "claim.created",
  "data": {
    "id": "0551c88b2249945151f967525ee3f7b4",
    "emr_claim_id": "73001",
    "emr_appointment_id": "264453",
    "emr_patient_id": "32191",
    "patient_name": "Jane Smith",
    "provider_name": "Dr. Michael Denenberg",
    "service_date": "2026-04-13",
    "claim_date": "2026-04-14",
    "claim_status": "PEN",
    "claim_status_description": "Pending",
    "claim_type": "0",
    "void_flag": false,
    "total_charge": "1233.87",
    "total_payment": "0.00",
    "net_payment": "0.00",
    "balance": "1233.87",
    "net_adjustment": "0.00",
    "patient_responsibility": "0.00",
    "icd_codes": [
      {
        "code": "Z01.411",
        "primary": "1",
        "description": "Encounter for gynecological examination with abnormal findings",
        "icd_version": "10"
      }
    ]
  }
}

Data Fields:

Field	Type	Description
`id`	string	Cobalt’s unique identifier for the claim
`emr_claim_id`	string	The EHR’s native claim ID
`emr_appointment_id`	string	The EHR’s appointment/encounter ID the claim belongs to
`emr_patient_id`	string	The EHR’s patient ID
`patient_name`	string	Patient’s full name
`emr_provider_id`	string	The EHR’s provider ID
`provider_name`	string \| null	Rendering provider’s name
`service_date`	string	Date of service (YYYY-MM-DD)
`claim_date`	string	Claim date (YYYY-MM-DD)
`claim_status`	string	EHR claim status code (e.g. `PEN`)
`claim_status_description`	string	Human-readable claim status
`claim_type`	string	EHR claim type code
`void_flag`	boolean	Whether the claim is voided
`total_charge`	string	Total billed amount
`total_payment`	string	Total payment received
`net_payment`	string	Net payment
`balance`	string	Outstanding balance
`net_adjustment`	string	Net adjustment
`patient_responsibility`	string	Patient responsibility amount
`icd_codes`	array	ICD-10 diagnosis codes on the claim

claim.updated

Triggered when a synced claim changes in your EHR. Only fires when a header field actually changed (for example a status, payment, or balance update), so unchanged claims re-seen during a sync do not emit an event.Payload Example:

{
  "id": "759df7ac268844a9926c58d36376b413",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "created": "2026-07-13T05:41:22.104Z",
  "type": "claim.updated",
  "data": {
    "id": "0551c88b2249945151f967525ee3f7b4",
    "emr_claim_id": "73001",
    "emr_appointment_id": "264453",
    "emr_patient_id": "32191",
    "patient_name": "Jane Smith",
    "service_date": "2026-04-13",
    "claim_status": "PAID",
    "claim_status_description": "Paid",
    "total_charge": "1233.87",
    "total_payment": "1050.00",
    "balance": "0.00",
    "updated_fields": {
      "claim_status": "PAID",
      "total_payment": "1050.00",
      "balance": "0.00"
    }
  }
}

Data Fields:The full claim object (same fields as claim.created) plus:

Field	Type	Description
`updated_fields`	object	Map of the fields that changed, with their new values

Introduction

Guides

Payload Envelope

Appointment Events

Patient Events

Claim Events

​Payload Envelope

​Appointment Events

​Patient Events

​Claim Events

Payload Envelope

Appointment Events

Patient Events

Claim Events