Content-Type: application/json and includes generated-at and X-API-Key headers so you can verify the request before you trust the body. Refer to Signature verification for those steps.
Read the top-level status field in the JSON and branch your handler on the event type. For session completion and session failure, the API reference documents "success" and "failure" payloads with example JSON. For session timeout and session cancellation, the payload includes session_id and encounter_id; refer to the sections below for what to do next.
You can use the following event types to handle the notifications:
Session completion
Session failure
Session timeout
Session cancellation
The Asynchronous notifications (webhook) API reference documents
success and failure payloads with example JSON. Timeout and cancellation are webhook events listed in this guide; the API reference does not yet include example JSON for those events.Session completion
When an ambient session finishes and note generation completes successfully, your endpoint receives a session completion notification. Whenstatus is "success": The payload identifies the session and encounter and provides links to retrieve results. It includes:
session_id,encounter_id(always present)- Optionally:
sessions,additional_info,_links
_links, each key is an array of link objects (href, method, name, type).
Following are the keys you will see in the _links object:
contents: Session-level note content.encounter_content: Encounter-level content.structured_data: Session-level structured clinical data.encounter_structured_data: Encounter-level structured clinical data.status: Status checks.transcripts: Transcripts.
_links object to fetch session content, encounter content, structured clinical data, status, and transcripts from the Ambient APIs. For each link, combine its href with your API base URL and use the correct authentication when you call those follow-up APIs.
The sessions array lists the session IDs tied to the encounter so far.
For an example JSON body, refer to Payload & Response.
Session failure
When the ambient session or note generation fails, your endpoint receives a session failure notification. Whenstatus is "failure": The payload identifies the session and encounter and describes the error. It includes:
session_id,encounter_id,error_code,error_detail
error_code and error_detail to log the failure, trigger alerts, or show an error in your application. The API reference example uses ERROR_CODE_TRANSCRIPTION with detail Error in transcription.
For an example JSON body, refer to Payload & Response.
Session timeout
When an ambient session times out, your endpoint receives a session timeout notification. The payload includessession_id and encounter_id. The API reference does not yet document other fields or example JSON for this event.
Record the identifiers and update your application state. If you need the current processing state, refer to Ambient Session Status.
Session cancellation
When an ambient session is cancelled, your endpoint receives a session cancellation notification. The payload includessession_id and encounter_id. The API reference does not yet document other fields or example JSON for this event.
Record the identifiers and update any in-progress state for that session. To confirm how the session ended on the platform, refer to Ambient Session Status. Documented status values there include aborted, which means the ambient session was cancelled by the user or client.