Docs
View as Markdown

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.

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:

  1. Take the body exactly as received, before parsing it.
  2. Work out HMAC-SHA256 of t + "." + body with your webhook secret (the whole string, whsec_ included) as the key, in hex.
  3. Accept if it equals any v1 (in constant time) and t is 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.