Developers
A clinic with a website, a group with a warehouse, a partner with a dashboard — none of them should have to wait for us to build something.
Webhooks
Signed, with retries. Set one up in the interface and the signing secret is shown once.
| Event | Fires when |
|---|---|
appointment.booked | Somebody books, from any route |
appointment.cancelled | A visit is cancelled |
referral.received | A referral arrives by fax, portal or by hand |
referral.advanced | A referral moves to a new stage |
form.completed | A patient finishes an intake form |
payment.received | Money is recorded |
order.placed | A clinician orders something |
message.received | A patient replies |
Identifiers and states. Never a name, a number or a clinical detail — a webhook goes to a server we do not control, at a URL somebody typed into a form, and anything else would make every integration a patient-data export that nobody reviewed.
When you need the detail, ask for it having proved who you are.
Every request carries X-Essentials-Signature, an HMAC-SHA256 of the timestamp
and the raw body joined with a dot, plus X-Essentials-Signature-Timestamp.
Compare in constant time and reject anything older than five minutes.
Retries happen, and your acknowledgement can be lost on the way back. Every event carries
an id in both the header and the body — X-Essentials-Event-Id — precisely so
you can recognise a repeat.
A subscriber that keeps failing is switched off rather than retried for ever, and we keep your server's own reply so "we never got it" has an answer.
signature = hmac_sha256(timestamp + "." + raw_body, your_secret)
Where it is set up
A practice adds a subscription itself: an HTTPS address, the events it wants, and a secret shown once. Every delivery is kept with the status code your end returned, and a subscription that keeps failing switches itself off rather than retrying for ever.
The capability map
Before writing code that creates a lab order, ask whether the EMR on the other side can accept one. The map answers per resource and per operation, and an unsupported call returns a specific "not supported" with a sentence you can show a user — never a silent success.
This is the difference between an integration that degrades and one that lies. If your code treats "cannot" and "failed" the same way, it will retry the impossible for ever and lose the possible.
The canonical model
Patient, Practitioner, Location, Appointment, Encounter, Coverage, DocumentReference and Order. Every record carries where it came from — which EMR, which connection, which id there, and when it was last changed — so provenance is never guessed.
Identifiers are ours, minted once and stable for ever. Reconnecting an EMR does not create a second copy of every patient, which is the failure that makes most integrations unusable in their second year.
The API
There is a read and write API behind the same signing scheme. It is not open to the public yet because we would rather stabilise it with a few partners first than publish something we have to break. Ask, and we will bring you in.
