Skip to main content

​
Polling Interval

A poll interval of 1 second works well for most operations. Cobalt typically processes operations within a few seconds to a couple of minutes depending on the EHR system. If you want to reduce API calls, you can increase the interval to 2-3 seconds with minimal impact on perceived latency.

​
Timeout

Set a timeout based on the operation type:
OperationRecommended Timeout
Appointments2 minutes
Patients2 minutes
Notes3 minutes
Documents3 minutes
Insurance2 minutes
Processing times vary by EHR system. If you experience frequent timeouts, increase the timeout rather than reducing the poll interval.

​
Handle Timeouts Gracefully

A timeout does not mean the operation failed. It means the result wasn’t available within your wait window. The operation may still complete successfully in the background. If a timeout occurs:
  1. Log the job_id so you can look it up later.
  2. Check back later by calling GET /v1/webhook-events?job_id={job_id} at any point in the future.
  3. Don’t retry the original operation unless you’ve confirmed it failed. Creating a duplicate appointment or patient is worse than waiting a bit longer.
try {
    const result = await awaitResult(jobId, { timeoutMs: 120000 });
    // Handle success or failure
} catch (error) {
    if (error.message.includes('Timed out')) {
        // The operation may still succeed - don't retry blindly
        console.log(`Operation still processing. Track with job_id: ${jobId}`);
    }
}

​
When to Use Webhooks Instead

Polling works well for low-volume, on-demand operations. For high-volume or background processing, webhooks are more efficient:
  • Use polling when a user is waiting for an immediate result (e.g., a “Schedule Appointment” button in your UI).
  • Use webhooks when processing records in bulk or when operations happen in the background without a user waiting.
  • Use both for the best of both worlds: webhooks for production event processing, polling for ad-hoc operations and debugging.
You do not need to register a webhook URL to use the polling approach. Cobalt tracks all operation results internally regardless of whether you have webhooks configured.

​
Supported Operations

Any Cobalt API operation that returns a job_id in its response supports this polling pattern. This includes:
  • Appointments - Create and update
  • Patients - Create
  • Notes - Create
  • Documents - Upload
  • Tasks - Create
  • Messages - Create
  • Insurance - Add to patient
  • Referring Providers - Create
  • Telephone Encounters - Create