Referral Status Webhooks

Receive lifecycle updates from intake through enrollment and active patient‑months.

Registering Endpoints

• Provide an HTTPS URL (TLS 1.2+) and shared secret; payloads are signed with HMAC SHA-256 in X-ICP-Signature.
• Retries use exponential backoff for 24 hours; deliveries are idempotent by eventId.
• Allowlist our source IPs if your firewall supports it.

Verifying Signatures

Node.js example:

import crypto from "node:crypto";

export function verifySignature(req: Request, secret: string) {
  const theirs = req.headers.get("x-icp-signature");
  if (!theirs) return false;

  const raw = await req.text(); // ensure raw body access
  const mine = crypto.createHmac("sha256", secret).update(raw).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(theirs, "hex"),
    Buffer.from(mine, "hex")
  );
}

Python:

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(digest, signature)

Events

• referral.accepted – payload validated; outreach scheduled.
• referral.contact_attempted – contact attempt with outcome.
• referral.consent_obtained – timestamp and method recorded.
• referral.initiating_visit.scheduled – visit date/time and modality.
• referral.enrolled – BHCM enrollment complete.
• cocm.apm_activated – first active patient‑month started.

Example

{
  "eventId": "evt_789",
  "type": "referral.enrolled",
  "createdAt": "2025-11-12T15:23:11Z",
  "data": {
    "referralId": "ref_12345",
    "patientId": "pat_456",
    "correlationId": "corr_abc",
    "enrolledAt": "2025-11-10T18:01:00Z"
  }
}

Error Handling

• Respond 2xx within 10 seconds to acknowledge. Non‑2xx responses trigger retries.
• Validate the HMAC before processing; discard duplicates by eventId.
• Retry policy (default):

Attempt	Delay
1	immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours
7	24 hours

• After 24 hours, unresolved events are surfaced to Partner Ops with your contact information.