Webhooks

Webhooks let Medblocks notify your backend the instant something happens in Connect. A PatientFlow finishes, a refresh token stops working, a background pull settles. Your server registers an HTTPS endpoint and Medblocks delivers signed JSON payloads to it.

This section covers everything you need to consume webhooks. Building a receiver, verifying signatures, managing endpoints from your backend, retries, and replaying events. For the underlying model read Concept · Webhooks.

Event Catalog

Event type	Fires when	Use it for
`patient_flow.completed`	Patient finished the hosted flow (success or failure).	Update your “connected” UI, kick off downstream workflows.
`connection.token_refresh_failed`	A previously active connection lost its refresh token.	Prompt the patient to reconnect.
`records.sync.completed`	A background pull finished and new records are available.	Trigger downstream processing, refresh dashboards.
`records.sync.failed`	A background pull errored.	Page the on-call team.

In This Section

Quickstart

Events Catalog

Payload shape for every event type.

Signatures

Medblocks-Signature header, constructEvent, and the raw-body trap.

Managing Endpoints

mb.webhooks.*. Create, list, update, rotate, delete from your backend.

Retries & Auto-Disable

Backoff schedule, endpoint auto-disable, reactivation.

Redelivery

Manual re-enqueue after fixing a receiver bug.

Local Development

Tunneling, fixtures, replaying events.

Receiver Contract

At a glance, your receiver must:

Accept POST requests over HTTPS with a JSON body.
Read the raw request body (no JSON pre-parsing) before computing the signature.
Verify the Medblocks-Signature header against the raw body and your endpoint’s signing secret.
Return a 2xx response within 5 seconds (otherwise Medblocks retries).
Be idempotent. The same event.id may be delivered more than once.

Everything else is the SDK’s job. Medblocks.webhooks.constructEvent(rawBody, signature, secret) does steps 3 and returns a typed WebhookEvent you can switch over.

Quick Sketch

import { Medblocks, MedblocksSignatureError } from "@medblocks/connect";

async function handle(req: Request): Promise<Response> {
  const rawBody = await req.text();
  const signature = req.headers.get("Medblocks-Signature");

  try {
    const event = await Medblocks.webhooks.constructEvent(
      rawBody,
      signature,
      process.env.MEDBLOCKS_WEBHOOK_SECRET!,
    );

    if (event.type === "patient_flow.completed") {
      const flow = event.data.object;
      // ...your business logic
    }

    return new Response("ok", { status: 200 });
  } catch (err) {
    if (err instanceof MedblocksSignatureError) {
      return new Response("bad signature", { status: 400 });
    }
    throw err;
  }
}

The Quickstart expands this with route wiring, raw-body handling per framework, and event.type discrimination.

Concept · Webhooks. Model and lifecycle.
Managing Endpoints. mb.webhooks.* reference.
Reference · Register a webhook endpoint.