How a write reaches the health record system

NexHealth keeps a copy of each practice's data and keeps it in sync with the health record system. Reads come from that copy. Writes go to NexHealth first and into the health record system afterwards.

sequenceDiagram
    participant A as Your app
    participant N as NexHealth
    participant H as Health record system
    A->>N: POST /appointments
    N-->>A: 201 Created. The record is accepted.
    N->>H: Write the appointment
    H-->>N: Saved, or failed
    N-->>A: Webhook: appointment_insertion

Reads

NexHealth reads from the health record system on a cycle. A change made in the health record system can take several minutes to show up in the API.

Sync status tells you how fresh the data is for a location.

Writes

A write has two stages.

Accepted. You call the API, for example POST /appointments. A successful response means NexHealth accepted the record. It is not in the health record system yet.
Written. NexHealth writes the record into the health record system. When that finishes, NexHealth sends you a webhook.

How to tell whether a write landed

Subscribe to the insertion event for each resource you write. Do this before you start writing.

You write	Subscribe to
Appointments	`appointment_insertion`
Payments	`payment_insertion`
Adjustments	`adjustment_insertion`
Patient documents	`document_insertion`
Form responses	`form_response_insertion`

The event name carries the result. For an appointment you receive one of these.

Event	What it means
`appointment_insertion.complete`	The appointment is in the health record system.
`appointment_insertion.failed`	NexHealth tried to write the appointment and the write did not succeed.
`appointment_insertion.timed_out`	The write could not reach the health record system before the start time of the appointment passed.

You can also read the record back. An appointment that has not been written has foreign_id set to null and last_sync_time set to null. Once it is written, foreign_id holds the ID of the appointment in the health record system.

See Setting up webhooks for setup and the Webhook Subscriptions reference for every event and payload.

How long a write takes

There is no fixed time. When the sync is online, writes usually complete quickly. A write waits when the sync is offline.

Server-based systems. The sync is offline when the office server is off.
Cloud-based systems. The sync is offline when nobody at the office is logged in to the NexHealth Chrome extension and the health record system.

Do not hold a patient or a caller waiting for the webhook.

When a write fails

NexHealth does not retry a failed write automatically. Before you send it again, read the original record and confirm that foreign_id is still null.

Troubleshooting appointment writes lists the common causes and what to do for each.

What this means for your app

Treat a successful response as accepted, not done.
Store the NexHealth id and match webhook events to it.
Handle failed and timed_out as follow-up work, for example by offering another time.
Check the sync status of a location before you offer times.