Webhooks
Signed events sent to your server as things happen, and how to check them.
Give us an https:// address on the public internet and we POST each event to it as it
happens. You can ask for some kinds of event only, or some practices only.
{"id": "8a6f0c0e-…", "type": "booking.changed",
"created_at": "2026-11-21T10:02:11.5+00:00",
"practice_id": "…",
"data": {"booking_id": "…", "by": "patient", "starts_at": "2026-11-24T14:00:00+00:00"}}
An event never carries a patient's name, contact details or a comment. New kinds of event and new fields may be added: ignore what you do not know.
Answer quickly
Answer 2xx within ten seconds and do your own work afterwards. Anything else is tried
again after 1, 5 and 30 minutes and 2, 6 and 12 hours, then we stop.
- The same event may arrive twice. Keep the event
idand ignore one you have had. - Events may arrive out of order. Use
created_at.
Check the signature
Each request carries a header VroomLogic-Signature: t=<unix seconds>,v1=<hex> (to be
renamed Orkero-Signature). Check it before you believe an event:
- Take the body exactly as received, before parsing it.
- Work out HMAC-SHA256 of
t + "." + bodywith your webhook secret (the whole string,whsec_included) as the key, in hex. - Accept if it equals any
v1(in constant time) andtis within five minutes of now.
There are two v1 values for a day after a secret is replaced, so you can change over
without missing an event.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function fromOrkero(secret: string, header: string, rawBody: string): boolean {
const parts = (header ?? '').split(',').map((p) => p.trim());
const t = parts.find((p) => p.startsWith('t='))?.slice(2);
const given = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
if (!t || given.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'));
return given.some((v) => v.length === expected.length && timingSafeEqual(Buffer.from(v), expected));
}
import hashlib, hmac, time
def from_orkero(secret: str, header: str, raw_body: bytes) -> bool:
parts = [p.strip() for p in (header or "").split(",")]
t = next((p[2:] for p in parts if p.startswith("t=")), None)
given = [p[3:] for p in parts if p.startswith("v1=")]
if not t or not given or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(v, expected) for v in given)
Kinds of event
type |
When |
|---|---|
booking.booked, booking.changed, booking.cancelled |
A booking your key made was made, moved or cancelled. |
feedback.request_sent |
The question went. |
feedback.answer_received |
The person gave a score. |
feedback.score_changed |
They changed it (within 24 hours). |
feedback.comment_added |
They left a comment (the comment itself is not sent). |
feedback.low_score |
A score of 0 to 6 (sent after two minutes, in case of a mis-tap). |
feedback.opted_out |
"Don't ask me again." |
accounts.day_ready, accounts.day_revised |
A day's figures were worked out, or worked out again. |
call.completed, call.handover, call.callback_needed |
Voice (early access). |
webhook.test |
A test sent at your request. |