# Webhooks

> Signed events sent to your server as things happen, and how to check them.

Source: https://docs.orkero.app/webhooks

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.

```json
{"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 `id` and 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:

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.

```typescript
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));
}
```

```python
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. |
