Webhooks

Base https://bluebananaehr.com. Auth is Authorization: Bearer bb_…; the key decides the tenant.

• Up to 25 subscriptions per tenant, enabled or not; the next create answers 429.
• Validation errors answer 422 with an OperationOutcome.
• Another tenant's subscription id answers 404.
• The secret is 64 hex characters and is never shown again. To change it, create a new subscription and delete the old one.
• name is required, at most 80 characters. enabled defaults to true.

curl -X POST https://bluebananaehr.com/api/subscriptions \
  -H "Authorization: Bearer bb_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment cancelled",
    "trigger": { "kind": "event", "events": ["appointment.cancelled"] },
    "destination": { "kind": "http", "url": "https://example.com/hook" }
  }'

criteria

• resourceType: any of the 43 supported types.
• interactions: any of create, update, delete. Default ["create", "update"].
• fhirpath: up to 10 boolean expressions, each at most 1000 characters, AND-combined. %previous is the version before the write.
• changed: 1–10 FHIRPath paths; fires only if at least one evaluates differently from the previous version. On create every set field counts as changed.
• Transitions: "changed": ["status"], "fhirpath": ["status = 'cancelled'"] fires once per cancellation; "fhirpath": ["%previous.start != start"] fires on a reschedule.

template

• Appointment templates send the Appointment as it reads at fire time, and skip it if it was deleted, cancelled or rescheduled in the meantime.
• Schedules are evaluated every 5 minutes. A cron expression that fires more often misses the fires in between.

47 events. Each is a preset criteria filter; status events fire when the status becomes that value. Names are stable. Machine-readable list: GET /api/subscriptions/events.

{
  "delivery_id": "del_…",
  "subscription_id": "sub_…",
  "tenant": "dev-…",
  "event": {
    "type": "criteria.matched",
    "fired_at": "2026-09-30T14:05:00.000Z",
    "interaction": "update",
    "trigger": { "kind": "event", "resourceType": "Appointment" },
    "name": "appointment.cancelled",
    "names": ["appointment.cancelled", "appointment.updated"]
  },
  "data": {
    "resource": { "resourceType": "Appointment", "id": "…", "status": "cancelled", "meta": { "versionId": "3" } },
    "previous": { "resourceType": "Appointment", "id": "…", "status": "booked", "meta": { "versionId": "2" } },
    "changes": ["status"],
    "context": { "patientId": "…", "practitionerId": "…", "status": "cancelled", "start": "…", "end": "…" }
  }
}

• event.interaction: create, update or delete. On delete, data.resource is the last version.
• event.names: the subscribed events this write matched (event triggers only); event.name is the first. One delivery per write per subscription.
• Updates add data.previous (the version before the write) and data.changes (top-level fields that differ, ignoring meta, extension, id, text).
• meta.versionId is 1 on create and +1 per update.
• Every resource carries the http://bluebananaehr.com/synthetic-data extension.
• data.context: flat fields for mapping without parsing references. patientId for any patient-linked resource; Appointments add practitionerId, status, start, end and reason. Missing values are left out.
• Test deliveries carry data.context.test = true.

• destination: { "kind": "http", "url": "https://…", "headers": { … } }. http is the only kind.
• Up to 8 static headers, values at most 256 characters. Host, Content-Length, Content-Type and X-Keragon-* are reserved.
• URLs resolving to private, loopback, link-local or unique-local addresses are rejected at registration and again at delivery. So are bluebananaehr.com URLs, except the echo sink.
• Redirects are not followed.
• You cannot supply the secret; the server generates it.

HMAC-SHA256 over ${t}.${rawBody} with the subscription secret, hex-encoded. Compare in constant time and reject if |now − t| exceeds 300 seconds.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody: string, header: string, secret: string): boolean {
  const m = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header.trim());
  if (!m) return false;
  const t = Number(m[1]);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(m[2], 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

A fire whose subscription was deleted or disabled before delivery is dropped.

• GET /api/subscriptions/{id}/deliveries?limit= (1–200, default 50): one row per attempt, newest first — delivery_id, attempt, event_type, event_name, resource_ref, url, status_code, ok, duration_ms, error, created_at. The last 200 attempts are kept per subscription.
• Test delivery: the MCP tool test_webhook_subscription sends a sample payload built from a real sandbox resource, with data.context.test = true.
• Echo sink: https://bluebananaehr.com/api/webhooks/echo answers 200 and stores nothing. Point a subscription at it, trigger it, then read the delivery log.