Webhooks

Planned Status

recording.transcript_ready is a planned public webhook contract with runtime status planned_not_generally_available. It is documented so receivers can prepare for the notification shape, but outbound delivery is not generally available yet.

The 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.

Payload Shape

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

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

webhook.endpoint_test is not part of this public webhook inventory.

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=a3cc6cb77b21da521f106cc32f59c3d119181f533faef8c7ff3e44f906053701
ChartHero-Webhook-Version: 2026-05-01

This example uses synthetic values. 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.

Retry and idempotency

Delivery is at least once. Receivers must dedupe business work by event id or ChartHero-Event-Id, not by ChartHero-Delivery-Id.

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

Follow-Up Fetches

Receivers fetch approved clinical resources through public REST routes after the webhook arrives. Activation approves a receiver-specific subset of candidate routes. The receiver API key must grant only the union of scopes required for those approved routes. recordings:read is required only when the audio route is approved.

Production availability

Clinical delivery remains unavailable until ChartHero has activated the receiver for a subscription. Activation confirms the approved follow-up routes, least-privilege receiver API-key scopes, webhook signing setup, receiver correlation, network allowlisting when applicable, and outbound delivery and audit readiness.

Clinical subscriptions default disabled. Activation records readiness and provenance atomically with the active subscription revision.

Management/setup availability controls setup surfaces only. It does not make deliveries available until receiver activation is complete.

Readiness revocation is future runtime behavior: disable affected clinical subscriptions and explicitly cancel already-created non-terminal unsucceeded work, including pending deliveries, currently leased sending deliveries, and expired/stale sending deliveries. This documentation placeholder does not implement those actions.

Correlation Status

Current receiver correlation status is not_confirmed_runtime_blocked. Runtime delivery cannot launch for the first receiver until ChartHero IDs are confirmed usable or an approved public correlation field is added to follow-up API responses.