API & Webhooks

Authentication

• Bearer tokens per organization
• Least privilege scopes by module

Headers and signatures

• Authorization: Bearer {token}
• Idempotency-Key: client-generated UUID for safe retries
• Webhook-Signature: HMAC SHA-256 of the raw body using the org secret

Webhooks

{
  "event": "consent.created",
  "org_id": "...",
  "patient_id": "...",
  "timestamp": "..."
}

• Events: consent.created, consent.revoked, visit.started, visit.closed
• Retries with exponential backoff; HMAC signature header

Verify webhook signature

Header: X-Cura-Signature with format sha256=hex(hmac_sha256(secret, rawBody))

const crypto = require("crypto");
function verify(req, secret) {
  const sig = req.headers["x-cura-signature"] || "";
  const raw = req.rawBody || JSON.stringify(req.body);
  const h = crypto.createHmac("sha256", secret).update(raw, "utf8").digest("hex");
  return sig === "sha256=" + h;
}

Rate limits and retries

• Use Idempotency-Key to avoid duplicate writes on retry
• Honor Retry-After for 429 responses
• Backoff strategy: 1s, 2s, 4s, 8s (max 5 attempts)