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.

Planned / not generally available: Runtime delivery for recording.transcript_ready is not generally available. Use this guide to prepare receiver behavior before activation.

The current documented event is recording.transcript_ready, sent when a recording transcript is ready for follow-up fetches. See Webhooks for the full planned 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=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, 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