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.

The current documented event is recording.transcript_ready, sent when a recording transcript is ready for follow-up fetches. Runtime delivery is planned/not generally available; see Webhooks for the full contract.

Required scopes

Receiving the webhook itself does not use ChartHero API-key scopes. Follow-up REST fetches require only the union of scopes for the receiver's approved routes:

recordings:read is required only when the audio follow-up route is approved.

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=a3cc6cb77b21da521f106cc32f59c3d119181f533faef8c7ff3e44f906053701" \
  -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_123","resources":{"encounter_id":"enc_123","document_id":"doc_123"}}'

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_123",
  "resources": {
    "encounter_id": "enc_123",
    "document_id": "doc_123"
  }
}

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

Response

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

HTTP/1.1 204 No Content

Deduplicate business work by event id or ChartHero-Event-Id, not by ChartHero-Delivery-Id.

Common errors

Next step

Implement Verify webhook signatures before making follow-up fetches. Then fetch only approved resources using Fetch encounters, Fetch documents, or Fetch transcript and audio. See recording.transcript_ready in the API Reference for the generated webhook contract.