Webhooks for the HealthTasks REST API

The HealthTasks REST API supports webhooks with signed JSON deliveries. See a sample payload and how to verify X-HealthTasks-Signature, then re-fetch via the API.

When we introduced the HealthTasks REST API, the goal was simple: connect clinical education data to the systems your program already runs.

That connection got stronger when clinical partners gained site-scoped access for placements, clearance, and unit updates. Schools and hospitals could share the same picture without overnight file drops.

Today that surface gets another step forward: webhooks.

Push when something changes

The REST API now supports optional webhooks. When placements, schedules, compliance, or units change, HealthTasks can notify your endpoint right away. Your systems learn that something moved, then pull the latest details from the API.

Configure an endpoint under Settings → REST API. Site-scoped connections only receive events for the locations they can access.

What a delivery looks like

HealthTasks POSTs thin JSON to your HTTPS URL. The body carries resource ids. Re-fetch full objects with the REST API. Webhooks are hints. Keep reconciling with updated_since polling.

Example payload for a placement change:

{
  "id": "evt_…",
  "type": "site_placement.updated",
  "created_at": "2026-07-14T12:00:00.000Z",
  "institution_id": "…",
  "data": {
    "classroom_id": "…",
    "user_id": "…",
    "location_id": "…"
  }
}

Each delivery also includes:

  • X-HealthTasks-Event — event type
  • X-HealthTasks-Event-Id — stable event id (evt_…)
  • X-HealthTasks-Delivery-Id — this delivery attempt
  • X-HealthTasks-Timestamp — ISO timestamp used in the signature
  • X-HealthTasks-Signature — sha256=<hex> HMAC of {timestamp}.{rawBody} with your whsec_… signing secret

Event types today: site_placement.updated, site_placement.schedule_updated, compliance.updated, location_unit.updated, plus ping for testing from Settings.

Verify the signature

Check the signature before you trust the body. Use the raw request body and the X-HealthTasks-Timestamp header:

import { createHmac } from "node:crypto";

function verifyHealthTasksSignature(rawBody, timestamp, signatureHeader, signingSecret) {
  const expected =
    "sha256=" +
    createHmac("sha256", signingSecret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");
  return signatureHeader === expected;
}

Why it matters

Pull-based sync already keeps school and hospital systems aligned. Webhooks make that loop tighter. Hospital schedulers and institutional tools can respond as soon as the roster, clearance status, or unit capacity updates. HealthTasks stays the system of record. Connected tools stay even closer to current.

Use webhooks alongside your existing sync. They are a faster signal on top of the API you already have.

Get started

Set up webhooks in HealthTasks under Settings → REST API. For setup details and the full API, see the documentation.