Events Catalog

The four event types and their payloads. event.type is the discriminator. After Medblocks.webhooks.constructEvent, TypeScript narrows event.data.object to the right shape.

Envelope

Every delivery uses the same envelope:

{
  "id": "evt_01J9YR9N3X4VZ6P2K5RH7M3LMP",
  "object": "event",
  "type": "patient_flow.completed",
  "api_version": "2026-04-25",
  "created_at": "2026-04-25T14:35:00.000Z",
  "data": { "object": { /* payload shaped by type */ } }
}

The WebhookEvent type re-exported from @medblocks/connect is a discriminated union over type.

patient_flow.completed

Fires when a patient finishes the hosted flow. Whether they connected an EHR, failed authorization, or just clicked Done. data.object is the full PatientFlow.

import type { WebhookEvent } from "@medblocks/connect";

function handle(event: WebhookEvent) {
  if (event.type !== "patient_flow.completed") return;
  const flow = event.data.object;

  const active = flow.connections.filter((c) => c.status === "active");
  const failed = flow.connections.filter((c) => c.status === "failed");

  console.log(`patient ${flow.patient_id}: ${active.length} active, ${failed.length} failed`);
}

Use it for: updating your “connected” UI, kicking off downstream onboarding, sending a welcome email.

connection.token_refresh_failed

Fires when a previously active connection’s refresh token stops working. The EHR rejected the refresh and we cleared the stored tokens. The patient needs to reconnect.

data.object is the single PatientFlowConnection that failed (the same shape you see inside PatientFlow.connections):

function handle(event: WebhookEvent) {
  if (event.type !== "connection.token_refresh_failed") return;
  const conn = event.data.object;

  console.warn(`connection ${conn.connection_id} needs reauth`);
  // Trigger a "please reconnect" email / push notification
}

Use it for: prompting the patient to start a new PatientFlow against the same source.

records.sync.completed

Fires when a background pull for one (patient, connection) pair finishes successfully and new records have landed.

function handle(event: WebhookEvent) {
  if (event.type !== "records.sync.completed") return;
  const sync = event.data.object;

  console.log(
    `patient ${sync.patient_id}: pulled ${sync.total} resources in ${sync.duration_ms ?? "?"}ms`,
  );
}

Use it for: triggering downstream processing, refreshing dashboards, telling a workflow the patient is ready.

records.sync.failed

Fires when a background pull errored without recovering.

function handle(event: WebhookEvent) {
  if (event.type !== "records.sync.failed") return;
  const failure = event.data.object;

  alerting.page("medblocks sync failed", {
    patient: failure.patient_id,
    connection: failure.connection_id,
    error: failure.error_message,
  });
}

Use it for: paging on-call, surfacing the failure in your ops dashboard, retrying via Medblocks support.

Endpoint Auto-Disable

After the delivery worker exhausts retries on one of your endpoints, that endpoint is flipped to status: "disabled" — no event is emitted for this transition. Detect it by reading status on the endpoint via GET /webhooks/{id} or mb.webhooks.retrieve(id), or by polling mb.webhooks.list() on a cron and alerting on any row with status === "disabled". Re-enable via mb.webhooks.update(id, { status: "active" }). See Retries & Auto-Disable.

Picking The Right Subscription

Subscribing to ["*"] delivers all four. Subscribing to a narrow list (max 4 types) is cheaper for your receiver to handle.

Related

• Signatures. Verifying the delivery.
• Managing Endpoints · Create. Programmatic subscription.
• Reference · Register a webhook endpoint. Exact request schema.