Skip to main content
Writes and the change feed described below are live for inventory (any plan with API access); for patients, appointments, clinical notes and drug requests, a write also needs the clinic’s API add-on and an accepted API data agreement — see the index page. Webhooks are set up from the developer dashboard’s Webhooks page — see Verifying a webhook’s signature.
Two different problems share one shape here: a write that might have been sent twice, and a webhook you might have missed. Both are solved the same way — a number or a key you keep, and pass back on your next request.

Idempotency keys — for writes

Every write endpoint (anything that creates, adjusts, or changes a record — receiving stock, adjusting a quantity, transferring between locations, creating an item, uploading a code list) accepts an Idempotency-Key header.
Generate a fresh key (a UUID is a good choice) once, when the action is first attempted — never a new one on every retry. If your request times out, or you’re not sure whether it was received, retry with the same key:
  • If the original write never reached the server, the retry is the first attempt — it goes through normally.
  • If the original write already succeeded, the retry returns the same result it returned the first time (idempotent_replay: true in the response) and changes nothing a second time. You will never end up with a duplicated stock movement or a doubled adjustment from retrying.
A write endpoint that requires this header refuses a request with none — there is no way to opt out of it on a route where a duplicate would be a real problem (money, stock).

The sequence number — for webhooks

Every webhook carries a seq — a number that only ever goes up, counted separately for each clinic (and, for an event about your workspace itself, for your workspace). Store the highest seq you’ve successfully processed. It’s your one source of truth for “have I seen this already”, independent of whether the delivery itself arrived once, twice, or out of order under retry.
The event’s own id is not in the body: it arrives in the webhook-id header, and a retry or replay of the same event carries the same id (with a fresh timestamp and signature).

The change feed — catching up after downtime

If your endpoint was down, disabled, or you simply missed a delivery, don’t try to reconstruct what changed from memory — page through the change feed instead, starting after the last seq you have. The feed is per clinic — after_seq is the query parameter:
Keep paging with next_after until it stops advancing. The feed only ever returns event types your key’s current scopes cover — if a scope was removed since an event was queued, that event simply will not appear, the same as if it had never happened for you.
The change feed has a retention window (30 days, in the current design) — it is a catch-up mechanism for a short outage, not a permanent audit log of everything that ever happened.

See also