Skip to main content
Cobalt sends webhook events to notify you about activities in your EHR system. Each event contains structured data about what happened, allowing you to build real-time integrations and automate workflows.

​
Event Categories

Webhook events are organized into two main categories based on how they’re triggered:
  • Operation Events
  • Sync Events
Operation events are sent when Cobalt performs an RPA (Robotic Process Automation) action inside your EHR system. These confirm the success or failure of operations that Cobalt initiated on your behalf.Examples include creating appointments, adding patient insurance, uploading notes, and creating tasks.
The specific events available to you depend on your Cobalt configuration and EHR system. Contact your Cobalt representative to enable specific event types.

​
Event Structure

All webhook events share a common structure: 
{
  "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
  }
}
FieldTypeDescription
idstringUnique identifier for this event
access_token_reference_idstringYour reference ID associated with this webhook
objectstringAlways "event"
createdstringISO 8601 timestamp when the event was created
typestringThe event type (e.g., appointment.created)
job_idstringOptional API log ID for tracking the operation
dataobjectEvent-specific data payload

​
Structured Error Codes

Failure events (e.g., appointment.failed, patient.failed) now include structured error codes to help you programmatically handle different failure scenarios. This feature provides:
  • Machine-readable error codes - Parse errors programmatically instead of string matching
  • Context-aware descriptions - Error messages include specific details (MRN, provider names, etc.)
  • Backward compatibility - The legacy failure_reason field is still included

​
Error Response Structure

Failure events include both the legacy failure_reason field and a new 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."
      }
    ]
  }
}
Fields:
  • failure_reason (string) - Human-readable error message for backward compatibility
  • reasons (array) - List of structured error objects, each containing:
    • code (string) - Machine-readable error code
    • description (string) - Context-aware human-readable description
The failure_reason field is a concatenation of all description values from the reasons array, maintained for backward compatibility.

​
Using Structured Error Codes

You can programmatically handle different failure scenarios by checking the code field in the reasons array: 
// Example: Handle different appointment failure scenarios
function handleAppointmentFailed(webhookData) {
  const reasons = webhookData.data.reasons || [];

  for (const reason of reasons) {
    switch (reason.code) {
      case 'PATIENT_NOT_FOUND':
        // Update patient MRN or create patient first
        console.log('Action needed: Update patient MRN');
        updatePatientMrn(webhookData.data.mrn);
        break;

      case 'PROVIDER_UNAVAILABLE':
        // Find alternative time slots
        console.log('Action needed: Find alternative time slot');
        findAlternativeSlots(webhookData.data.appointment_id);
        break;

      case 'INVALID_VISIT_TYPE':
        // Map to valid visit type
        console.log('Action needed: Map visit type');
        mapVisitType(webhookData.data.appointment_id);
        break;

      default:
        // Handle unknown error codes
        console.log('Unknown error:', reason.description);
        alertSupport(reason);
    }
  }
}

# Example: Handle patient creation failures
def handle_patient_failed(webhook_data):
    reasons = webhook_data.get('data', {}).get('reasons', [])

    for reason in reasons:
        error_code = reason.get('code')

        if error_code == 'DUPLICATE_PATIENT':
            # Use existing patient
            existing_mrn = webhook_data['data'].get('existing_mrn')
            print(f'Patient exists with MRN: {existing_mrn}')
            use_existing_patient(existing_mrn)

        elif error_code == 'INSURANCE_NOT_FOUND':
            # Proceed without insurance or map to valid insurance
            print('Action needed: Map insurance company')
            map_insurance_company(webhook_data['data']['patient_id'])

        elif error_code == 'PERMISSION_DENIED':
            # Request elevated permissions or use different account
            print('Action needed: Check account permissions')
            request_permissions()

        else:
            # Handle unknown error codes
            print(f'Unknown error: {reason.get("description")}')
            alert_support(reason)

​
Migration from Legacy Error Handling

If you’re currently using failure_reason string matching, you can gradually migrate to structured error codes: Before (legacy approach): 
if (webhookData.data.failure_reason.includes('Patient not found')) {
  // Handle patient not found
}
After (with structured codes): 
const hasPatientNotFound = webhookData.data.reasons?.some(
  r => r.code === 'PATIENT_NOT_FOUND'
);

if (hasPatientNotFound) {
  // Handle patient not found
}
Backward-compatible approach: 
// Support both old and new formats
function hasError(webhookData, errorCode, legacyKeyword) {
  // Check new structured format first
  const hasStructuredError = webhookData.data.reasons?.some(
    r => r.code === errorCode
  );

  if (hasStructuredError) return true;

  // Fallback to legacy string matching
  return webhookData.data.failure_reason?.includes(legacyKeyword) || false;
}

// Usage
if (hasError(webhookData, 'PATIENT_NOT_FOUND', 'Patient not found')) {
  // Handle patient not found
}

​
Event Types Reference

​
Appointment Events

Triggered when Cobalt successfully creates an appointment in your EHR system, or when your staff creates an appointment (sync event).Type: Operation & SyncPayload 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:
FieldTypeDescription
appointment_idstringCobalt’s unique identifier for the appointment
mrnstringPatient’s Medical Record Number
date_timestringAppointment date and time (ISO 8601)
timezonestringTimezone for the appointment
provider_idstringPrimary provider’s ID
provider_namestringPrimary provider’s name
secondary_provider_idstring | nullSecondary provider’s ID (if applicable)
Triggered when an appointment is updated in your EHR system, either by Cobalt or by your staff (sync event).Type: Operation & SyncPayload 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:
FieldTypeDescription
idstringCobalt’s unique identifier for the appointment
ehr_appointment_idstringThe EHR’s native appointment ID
patient_mrnstringPatient’s Medical Record Number
patient_namestringPatient’s full name
datetimestringAppointment date and time (ISO 8601)
durationnumberAppointment duration in minutes
locationstringAppointment location/room
statusstringAppointment status code
provider_namestringProvider’s name
appointment_typestringType of appointment
appointment_modestringMode (e.g., “office”, “telehealth”)
updated_fieldsobjectFields that changed in this update
Triggered when Cobalt fails to create an appointment in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
appointment_idstringCobalt’s identifier for the failed appointment
mrnstringPatient’s Medical Record Number
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured 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
Triggered when Cobalt fails to update an existing appointment in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
appointment_idstringCobalt’s identifier for the appointment
mrnstringPatient’s Medical Record Number
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured 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
Triggered when an appointment’s status changes in your EHR system (sync event only).Type: SyncPayload Example:
{
  "id": "508c368e7de13b40f9397eec966d0330",
  "access_token_reference_id": "clinic_1",
  "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:
FieldTypeDescription
idstringCobalt’s unique identifier for the appointment
ehr_appointment_idstringThe EHR’s native appointment ID
patient_mrnstringPatient’s Medical Record Number
patient_namestringPatient’s full name
datetimestringAppointment date and time (ISO 8601)
statusstringNew appointment status
previous_statusstringPrevious appointment status
provider_namestringProvider’s name

​
Patient Events

Triggered when Cobalt successfully creates a patient in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
patient_idstringCobalt’s unique identifier for the patient
mrnstringPatient’s Medical Record Number
first_namestringPatient’s first name
last_namestringPatient’s last name
date_of_birthstringPatient’s date of birth (YYYY-MM-DD)
sexstringPatient’s sex
emailstringPatient’s email address
phonestringPatient’s phone number
Triggered when patient information is updated in your EHR system (sync event only).Type: SyncPayload Example:
{
  "id": "508c368e7de13b40f9397eec966d0331",
  "access_token_reference_id": "clinic_1",
  "object": "event",
  "created": "2025-07-28T10:20:15.491-07:00",
  "type": "patient.updated",
  "data": {
    "mrn": "MRN123456",
    "patient_name": "Jane Smith",
    "updated_fields": {
      "phone": "555-9999",
      "email": "jane.newemail@example.com"
    }
  }
}
Data Fields:
FieldTypeDescription
mrnstringPatient’s Medical Record Number
patient_namestringPatient’s full name
updated_fieldsobjectFields that changed in this update
Triggered when Cobalt fails to create a patient in your EHR system.Type: OperationPayload 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'. Please update the patient information using the PATCH /v1/patients/:id endpoint or search using GET /v1/patients.",
    "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:
FieldTypeDescription
patient_idstringCobalt’s identifier for the failed patient creation
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured error objects with code and description
existing_mrnstringMRN 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
Triggered when Cobalt successfully adds insurance information for a patient in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
patient_insurance_idstringCobalt’s unique identifier for the insurance record
patient_mrnstringPatient’s Medical Record Number
member_idstringInsurance member ID
group_idstringInsurance group ID
plan_begin_datestringInsurance plan start date (YYYY-MM-DD)
copaymentnumberCopayment amount
audit_trailarrayList of fields modified in the EHR
The audit_trail array shows all fields that were modified in the EMR during the insurance addition process, including before and after values.
Triggered when Cobalt fails to add insurance information for a patient in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
patient_insurance_idstringCobalt’s identifier for the insurance record
patient_mrnstringPatient’s Medical Record Number
errorstringDetailed explanation of why the insurance addition failed

​
Task Events

Triggered when Cobalt successfully creates a task in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
task_idstringCobalt’s unique identifier for the task
emr_task_idstringThe EHR’s native task ID
subjectstringTask subject/title
descriptionstringDetailed task description
assignee_user_idstringID of the user assigned to the task
patient_mrnstringPatient’s Medical Record Number (if applicable)
Triggered when Cobalt fails to create a task in your EHR system.Type: OperationPayload 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. Please update the patient MRN using the PATCH /v1/tasks/:id endpoint.",
    "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:
FieldTypeDescription
task_idstringCobalt’s identifier for the failed task
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured 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

Triggered when Cobalt successfully uploads a clinical note to your EHR system.Type: OperationPayload 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:
FieldTypeDescription
appointment_idstringCobalt’s appointment identifier
patient_mrnstringPatient’s Medical Record Number
note_typestringType of clinical note uploaded
provider_namestringName of the provider who authored the note
Triggered when Cobalt fails to upload a clinical note to your EHR system.Type: OperationPayload 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:
FieldTypeDescription
appointment_idstringCobalt’s appointment identifier
timezonestringTimezone for the appointment
mrnstringPatient’s Medical Record Number
reasonsarrayList 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

Triggered when Cobalt successfully uploads a document to your EHR system.Type: OperationPayload 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:
FieldTypeDescription
document_idstringCobalt’s unique identifier for the document
patient_mrnstringPatient’s Medical Record Number
folder_namestringEHR folder/category where document was uploaded
Triggered when Cobalt fails to upload a document to your EHR system.Type: OperationPayload 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:
FieldTypeDescription
document_idstringCobalt’s identifier for the document
patient_mrnstringPatient’s Medical Record Number
folder_namestringTarget EHR folder/category
reasonsarrayList 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
Triggered when Cobalt fails to upload a document to eClinicalWorks specifically.Type: OperationPayload 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:
FieldTypeDescription
document_idstringCobalt’s identifier for the document
patient_mrnstringPatient’s Medical Record Number
folder_namestringTarget EHR folder/category
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured 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

Triggered when Cobalt successfully creates a message in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
message_idstringCobalt’s unique identifier for the message
provider_idstringID of the provider who received the message
subjectstringMessage subject line
Triggered when Cobalt fails to create a message in your EHR system.Type: OperationPayload 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:
FieldTypeDescription
message_idstringCobalt’s identifier for the message
provider_idstringID of the target provider
failure_reasonstringDetailed explanation (legacy field, use reasons for new integrations)
reasonsarrayStructured 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

​
Testing Events

A test event used to verify webhook delivery and integration setup. You can trigger this event manually using the Send Test Webhook endpoint (POST /v1/webhook/test).Type: TestingPayload 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:
FieldTypeDescription
messagestringTest message content
timestampstringWhen the test event was generated
How to Use:Send a POST request to /v1/webhook/test with your authentication headers to trigger a test webhook:
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 will be sent to all configured webhook URLs for your client. Use this to:
  • Verify your webhook endpoint is receiving events correctly
  • Test your webhook signature verification logic
  • Validate your event processing pipeline
  • Debug webhook delivery issues
You must have at least one webhook URL configured using POST /v1/webhook before sending a test event.

​
Event Types Quick Reference

Event TypeCategoryOperationSyncDescription
appointment.createdAppointments✓✓Appointment created
appointment.updatedAppointments✓✓Appointment updated
appointment.failedAppointments✓Appointment creation failed
appointment.update_failedAppointments✓Appointment update failed
appointment.status_updatedAppointments✓Appointment status changed
patient.createdPatients✓Patient created
patient.updatedPatients✓Patient information updated
patient.failedPatients✓Patient creation failed
patient.insurance.addedPatients✓Insurance added successfully
patient.insurance.failedPatients✓Insurance addition failed
task.createdTasks✓Task created
task.failedTasks✓Task creation failed
note.uploadedNotes✓Clinical note uploaded
note.failedNotes✓Note upload failed
document.uploadedDocuments✓Document uploaded
document.failedDocuments✓Document upload failed
document.upload_failedDocuments✓Document upload failed (eCW)
message.createdMessages✓Message created
message.failedMessages✓Message creation failed
test.eventTesting--Test webhook delivery

​
Retrieving Webhook Events

You can retrieve past webhook events programmatically using the Get Webhook Events endpoint. This is useful for:
  • Debugging webhook delivery issues
  • Auditing event history
  • Recovering from webhook delivery failures
  • Testing your integration

​
Best Practices

Handle Idempotently

Webhook events may be delivered more than once. Use the id field to track which events you’ve already processed.

Respond Quickly

Return a 2xx status code as soon as you receive the webhook. Process the event asynchronously to avoid timeouts.

Verify Signatures

Always verify the cobalt-verification header to ensure the webhook came from Cobalt. See Receiving Webhooks for details.

Handle Failures

Monitor for .failed events and implement retry logic or alerting to handle operation failures gracefully.