Receive webhooks

When to use this

ChartHero webhooks are pointer notifications. Store the event identity, acknowledge with a 2xx response after lightweight validation, and fetch clinical resources through the public REST API.

ChartHero documents two events:

Branch on the body type. See Webhooks for the full contract and activation requirements.

Subscribe to events

An organization owner or admin sets up webhooks in ChartHero, under the organization's settings in Connections → Webhooks:

1. Create an endpoint with your receiver's HTTPS URL. ChartHero shows the endpoint's signing secret once; store it with your receiver's secrets.
2. Turn on each event the endpoint should receive. ChartHero sends an event only once its subscription is active.

If you don't see the Webhooks tab, contact ChartHero support.

Required scopes

Receiving the webhook itself does not use ChartHero API-key scopes and does not authorize PHI access. Follow-up REST fetches require only the union of scopes for the routes the receiver calls:

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. Successful PHI-bearing follow-up fetches are audited as public API disclosures; denied follow-up requests do not disclose PHI. recordings:read is required when the receiver uses the audio follow-up route, and evaluations:read when it fetches evaluations.

Request

curl -X POST "https://partner.example.test/chart-hero/webhooks" \
  -H "Content-Type: application/json" \
  -H "ChartHero-Event-Id: evt_recording_transcript_ready_01" \
  -H "ChartHero-Delivery-Id: whd_recording_transcript_ready_01" \
  -H "ChartHero-Timestamp: 1777649400" \
  -H "ChartHero-Signature: v1=a3bb0750eef64758be4a034aaff5dd5774c21bf7fe25083b51d61ba0214c0419" \
  -H "ChartHero-Webhook-Version: 2026-05-01" \
  --data-raw '{"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"}}'

Minimal event payload:

{
  "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"
  }
}

The webhook body does not include transcript turns, document content, evaluation results, patient demographics, audio URLs, endpoint secrets, or receiver-specific credentials.

An evaluation.completed body has the same envelope with evaluation_id, encounter_id, and document_id in resources:

{
  "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"
  }
}

After verifying it, fetch GET /external/v1/evaluations/{evaluation_id} and keep the newest evaluation per conversation, evaluated person, and definition.

The current 2026-05-01 payload fields are exact and do not allow additional properties. Future public payload additions require a new webhook API version after schema, docs, and changelog updates, and must remain thin pointer payloads.

Response

Return any HTTP 2xx response after signature verification and lightweight validation. No JSON acknowledgement body is required.

HTTP/1.1 204 No Content

Current delivery behavior uses a single automatic attempt per event/endpoint delivery. ChartHero does not currently guarantee automatic retry or redelivery for either event. Receivers must deduplicate business work by event id or ChartHero-Event-Id, not by ChartHero-Delivery-Id. Evaluation receivers also reconcile daily with the evaluation list.

ChartHero records outbound webhook delivery evidence separately from PHI access audit events. Follow-up public API fetches are audited separately as public API PHI disclosures.

Common errors