Best Practices

​

Polling Interval

​

Timeout

​

Handle Timeouts Gracefully

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

• 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.

​

Supported Operations

• Appointments - Create and update
• Patients - Create
• Notes - Create
• Documents - Upload
• Tasks - Create
• Messages - Create
• Insurance - Add to patient
• Referring Providers - Create
• Telephone Encounters - Create