> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/docs/webhooks/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:
```json theme={null}
{
"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](/docs/webhooks/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](/docs/webhooks/receiving) for details.
## Appointment Events
Triggered when EHR staff create an appointment in your EHR (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"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",
"local_datetime": "2025-07-28T09:00:00.000",
"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") |
Triggered when EHR staff update an appointment in your EHR (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"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",
"local_datetime": "2025-07-28T09:00:00.000",
"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 |
Triggered when an appointment's status changes in your EHR system.
**Payload Example:**
```json theme={null}
{
"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",
"local_datetime": "2025-07-28T09:00:00.000",
"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.
Triggered when EHR staff create a new patient in your EHR (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"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 |
Triggered when EHR staff update patient information in your EHR (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"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](/docs/webhooks/operation-events)).
## Claim Events
Triggered when a new claim is detected in your EHR (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"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 |
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:**
```json theme={null}
{
"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 |
## Document Events
Fired by the EHR document inbox sync. Each event carries the same document object
as [GET /documents](/api-reference/documents/list), without `created_at` /
`updated_at`.
Triggered when a new document lands in your EHR document inbox (detected by Cobalt's sync).
**Payload Example:**
```json theme={null}
{
"id": "8c1d4f0e2a9b4c7d9e6f1a2b3c4d5e6f",
"access_token_reference_id": "clinic_1",
"access_token_id": "550e8400-e29b-41d4-a716-446655440000",
"object": "event",
"created": "2026-10-05T14:02:12.418Z",
"type": "document.created",
"action": "ehr_sync",
"data": {
"id": "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12",
"file_name": "50_1a289685-9bcd-4f28-a00c-139ba48d506d.pdf",
"description": "Fax Inbox document",
"mime_type": "application/pdf",
"document_type": "file",
"patient_mrn": null,
"patient_ehr_id": null,
"encounter_ehr_id": null,
"folder_ehr_id": "137",
"folder_name": "Fax Inbox",
"assigned_to_ehr_id": "52685",
"assigned_to_name": "Smith,Jane",
"review_required": false,
"is_high_priority": false,
"tags": ["Referral"],
"scanned_date": "2026-10-05",
"service_date": null,
"has_file": false
}
}
```
**Data Fields:**
| Field | Type | Description |
| - | - | - |
| `id` | string | Cobalt document ID. Pass it to [POST /documents/fetch](/api-reference/documents/fetch) to get the file |
| `file_name` | string | Stored file name in the EHR |
| `description` | string \| null | Document description |
| `mime_type` | string | MIME type of the file |
| `document_type` | string | `file` or `visit_note` |
| `patient_mrn` | string \| null | Patient MRN; null while the document is not filed to a patient |
| `patient_ehr_id` | string \| null | The EHR's patient ID |
| `encounter_ehr_id` | string \| null | The EHR's encounter ID, when attached to one |
| `folder_ehr_id` | string \| null | The EHR's folder (category) ID |
| `folder_name` | string \| null | Folder (category) path |
| `assigned_to_ehr_id` | string \| null | Assignee's staff `ehr_id`; null for group assignees |
| `assigned_to_name` | string \| null | Assignee name as shown in the EHR |
| `review_required` | boolean | Whether the document is marked for review in the EHR |
| `is_high_priority` | boolean | Whether the document is high priority |
| `tags` | array | Document tags |
| `scanned_date` | string \| null | Date the document entered the inbox (YYYY-MM-DD) |
| `service_date` | string \| null | Service date (YYYY-MM-DD) |
| `has_file` | boolean | Whether Cobalt already stores the file |
Triggered when an inbox document changes in your EHR: reassigned, moved to another folder, filed to a patient, marked or unmarked for review, or re-prioritized. Only fires when a field actually changed.
**Payload Example:**
```json theme={null}
{
"id": "8c1d4f0e2a9b4c7d9e6f1a2b3c4d5e70",
"access_token_reference_id": "clinic_1",
"access_token_id": "550e8400-e29b-41d4-a716-446655440000",
"object": "event",
"created": "2026-10-05T15:22:40.031Z",
"type": "document.updated",
"action": "ehr_sync",
"data": {
"id": "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12",
"file_name": "50_1a289685-9bcd-4f28-a00c-139ba48d506d.pdf",
"folder_ehr_id": "501",
"folder_name": "Fax Inbox/Referrals",
"assigned_to_ehr_id": "61042",
"assigned_to_name": "Doe,John",
"review_required": false,
"updated_fields": {
"folder_ehr_id": "501",
"folder_name": "Fax Inbox/Referrals",
"assigned_to_ehr_id": "61042",
"assigned_to_name": "Doe,John"
}
}
}
```
The payload carries the full document object (shortened above) plus:
| Field | Type | Description |
| - | - | - |
| `updated_fields` | object | Map of the fields that changed, with their new values |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.