Webhooks

Availability

Two events are available. ChartHero sends them only to active subscriptions: a subscription starts turned off until your organization admin turns it on, as Receive webhooks describes.

The API Reference gives these events the status available_for_activated_subscriptions, meaning they are delivered only to active subscriptions.

Each event is a thin pointer notification. Receivers fetch clinical data through the public REST API after receiving the notification instead of expecting clinical artifacts in the webhook body.

You can turn on evaluation.completed once ChartHero releases evaluation routes in your environment.

Summary: verify the signature using the raw request body, deduplicate business work by event id or ChartHero-Event-Id, return any HTTP 2xx response for delivery success, and use follow-up REST fetches for clinical resources. Current delivery behavior does not schedule automatic retries.

Payload Shape

recording.transcript_ready

{
  "id": "evt_recording_transcript_ready_01",
  "type": "recording.transcript_ready",
  "api_version": "2026-05-01",
  "occurred_at": "2026-05-01T15:29:55Z",
  "organization_id": "org_synthetic_webhook_001",
  "resources": {
    "encounter_id": "enc_synthetic_webhook_001",
    "document_id": "doc_synthetic_transcript_001"
  }
}

evaluation.completed

{
  "id": "evt_evaluation_completed_01",
  "type": "evaluation.completed",
  "api_version": "2026-05-01",
  "occurred_at": "2026-09-14T15:09:40Z",
  "organization_id": "org_synthetic_001",
  "resources": {
    "evaluation_id": "eval_synthetic_001",
    "encounter_id": "enc_synthetic_001",
    "document_id": "doc_synthetic_transcript_001"
  }
}

occurred_at equals the evaluation's completed_at. ChartHero sends the event for every completed evaluation, including an older evaluation that completes after a newer evaluation of the same conversation. Keep the newest per conversation, evaluated person, and definition as described in How evaluations work. No event is sent for failed evaluations or for demo or training records.

Webhook examples use synthetic identifiers. The payload is intentionally minimal and excludes transcript turns, patient demographics, phone-call metadata, signed audio URLs, document content, evaluation scores and findings, endpoint URLs, storage keys, raw request or response bodies, IP addresses, user agents, and secrets.

Payload Evolution

The current 2026-05-01 payload fields are exact and this version does not allow additional properties. Same-version undeclared fields are not allowed.

Future additive public webhook fields require a new webhook API version after a schema, docs, and changelog update. Future versions must remain thin pointer payloads; embedded clinical payloads are not part of the current release.

A new event type changes no existing payload, so it joins the catalog under the current version. evaluation.completed uses 2026-05-01. Ignore or reject event types your receiver doesn't handle.

Headers

Delivery Header Example

ChartHero-Event-Id: evt_recording_transcript_ready_01
ChartHero-Delivery-Id: whd_recording_transcript_ready_01
ChartHero-Timestamp: 1777649400
ChartHero-Signature: v1=a3bb0750eef64758be4a034aaff5dd5774c21bf7fe25083b51d61ba0214c0419
ChartHero-Webhook-Version: 2026-05-01

This example uses synthetic values for the recording.transcript_ready example above. Every event uses the same headers. ChartHero-Timestamp is the delivery signing timestamp and is not necessarily the body occurred_at.

Signature Verification

Use the exact raw request body bytes as received. Build the signature input as {timestamp}.{raw_request_body}, where timestamp is the ChartHero-Timestamp Unix epoch seconds string. Verify the v1 HMAC-SHA256 digest from ChartHero-Signature with the endpoint signing secret, and reject timestamps outside the 300 second tolerance.

ChartHero-Event-Id must equal body id. ChartHero-Webhook-Version must equal body api_version.

Receiver Response

Any HTTP 2xx response is receiver success. No JSON acknowledgement body is required.

Current attempts and idempotency

Current delivery behavior uses a single automatic attempt per event/endpoint delivery. ChartHero does not currently guarantee automatic retry or automatic redelivery for either event. Reconcile evaluations at least daily with the evaluation list, as described in Fetch evaluations. Receivers must dedupe business work by event id or ChartHero-Event-Id, not by ChartHero-Delivery-Id, for receiver safety and future compatibility.

ChartHero-Delivery-Id identifies one event/endpoint delivery record and is support/debugging metadata only.

Follow-Up Fetches

Receivers fetch clinical resources through public REST routes after the webhook arrives. Receiving the webhook does not authorize PHI access. Each follow-up REST request independently enforces public API-key authentication, an organization-scoped active, unexpired, unrevoked API key, route rollout, required route scopes, and same-organization real-resource access. Document detail can return clinical documents, ambient transcripts, billing documents, or encounter checklists; ambient phone-call documents can include phone numbers and call logs.

Use an API key with only the union of scopes needed for the receiver's follow-up routes. Successful PHI-bearing follow-up fetches are audited as public API disclosures; denied follow-up requests do not disclose PHI. recordings:read is required only when the audio route is used, and evaluations:read only for the evaluation route.

Evidence and Audit

ChartHero records outbound webhook delivery evidence separately from PHI access audit events. The event id and ChartHero-Event-Id identify the webhook event, while ChartHero-Delivery-Id identifies one event/endpoint delivery for support and debugging.

Outbound webhook sends are delivery evidence, not PHI disclosures by themselves. Public API follow-up fetches for encounter, document detail with transcript content, audio, and evaluation data are audited separately as public API PHI disclosures.

Availability and activation

Deliveries start only when a subscription is activated, and every subscription starts turned off. Activation requires organization-admin authorization and a same-organization active, non-deleted, and not suspended endpoint, with a safe URL and a signing secret, for a supported event and payload version. ChartHero keeps a record of each activation.

Seeing the Webhooks tab doesn't start deliveries; only an active subscription does. Disabling an endpoint or a subscription stops its future deliveries, and ChartHero can cancel deliveries that haven't succeeded yet.