Ambient Webhook Overview

Understand when Suki sends Ambient webhooks, how to interpret session outcomes, and how to retrieve the results

Ambient webhooks notify your application when Suki finishes processing an ambient session. Your application can use the notification to check the session status and retrieve the results without repeatedly polling the API.

During partner onboarding, Suki configures a callback URL for your account. Suki sends notifications to this URL when an ambient session completes, is skipped, fails, or is aborted. The webhook contains the processing outcome, session identifiers, and links to the available results. It does not contain the generated note or other result content. Your application must retrieve that content through the API.

Ambient webhooks work with sessions created through the Ambient APIs, Web SDK, Mobile SDK, and Headless Web SDK. All these integration methods use the callback URL configured for your partner account.

​

Common use cases

Use the Ambient webhook when you want your application to react as soon as session processing finishes, instead of polling for status.

Write the Note to the EHR

When the notification reports SUCCESS and session status is completed, retrieve the note and write it into your EHR or EMR.

Open Note Review for the Clinician

Tell the clinician the note is ready, or that the session was skipped or failed and needs another recording.

Start Coding or Billing Work

Use the same notification to kick off E/M review, billing, or other document workflows that wait on the finished note.

Catch Failures Early

When the notification reports FAILURE, log error_code and error_detail, alert your team, and decide whether to ask the clinician to record again.

​

When Suki sends an Ambient webhook

Suki sends an Ambient webhook after you end a session and processing reaches a final outcome. This includes successful processing, skipped processing, processing failures, and aborted sessions.

Suki does not send a webhook when you create, start, pause, or resume a session.

The top-level status indicates the outcome reported by the notification:

Session outcome	Webhook status	What your application should do
Processing completed	SUCCESS	Check the session status. Retrieve the note and other results when the status is completed.
Processing skipped, such as when the recording is silent or too short	SUCCESS	Check the session status. When it is skipped, do not expect a generated note.
Processing failed	FAILURE	Record error_code and error_detail. Notify your application or user as appropriate.
Session aborted	FAILURE	Handle the notification as a failed session.

SUCCESS means processing reached a successful notification outcome. It does not guarantee that Suki generated a note. Always check the session status before retrieving or displaying the results.

​

Delivery rules

Your webhook receiver must account for the following behaviors:

• Cancelled sessions do not generate webhooks. When you send CANCEL while streaming, Suki stops the session without sending a webhook for it.
• A failed session can cause later sessions to be aborted. When an ambient session fails, Suki can abort other sessions recorded by the same user for that encounter if those sessions are still waiting to be processed. Each aborted session generates its own FAILURE webhook.
• A FAILURE notification does not always mean session processing failed. If error_code is ERROR_CODE_NOTIFICATION_GENERATION_FAILURE, Suki could not generate the webhook body. The session itself may have completed successfully. Check the session status before reporting a processing error.
• The same notification can be delivered more than once. Use session_id and status to identify and skip notifications your application has already processed.

Use the webhook as a signal to check the session, not as confirmation that the note is ready. Call Get ambient session status and retrieve the note only when the status is completed.

If you cancelled a session or suspect that you missed a notification, call the same endpoint to check the session’s current status.

For delivery behavior shared by all Suki webhooks, refer to Delivery rules.

​

How an Ambient webhook works

The following sequence shows how Suki delivers a notification and how your application retrieves the results.

1. End the Ambient Session

   Your application creates an ambient session, streams audio, and ends the session using the Ambient APIs or a Suki SDK.

2. Suki Processes the Session

   Suki transcribes the recording and generates the note, structured data, and any additional artifacts requested for the session.

3. Suki Sends the Webhook

   Suki sends a POST request to your configured callback URL. The request contains the processing outcome and session identifiers.

4. Verify the Request and Respond

   Your endpoint verifies the webhook signature and returns HTTP 200 within 30 seconds. Refer to Signature verification.

5. Check the Status and Retrieve Results

   When the notification reports SUCCESS, call the status link first. Retrieve the note and other results only when the session status is completed. Refer to Retrieve ambient results.

​

Handle skipped sessions

A SUCCESS notification does not always mean that Suki generated a note.

When a recording is silent or too short to process, Suki skips note generation but still sends a SUCCESS webhook. The session status is skipped, and there is no note to retrieve.

Before opening the note review screen:

1. Check Session Status

   Call Get ambient session status.

2. Read the Returned Status

   Check the status value in the response.

3. Continue Only When Completed

   Continue to note review only when the status is completed.

4. Handle Skipped Sessions

   When the status is skipped, offer the clinician an option to record the visit again instead of displaying an empty note.

For the complete status-handling flow in your application, refer to Track note generation status.

​

Handle encounters with multiple sessions

An encounter can contain multiple ambient sessions. For example, a clinician might record a visit in two separate parts.

Suki sends a separate webhook for each session. Each notification describes the encounter and its sessions up to that point.

The payload contains the following information:

• session_id identifies the ambient session that triggered the notification.
• sessions lists all ambient sessions in the encounter, ordered from oldest to newest.
• Session-level links, such as contents and transcripts, contain one link for each session listed in sessions. Use the link whose name matches the session you want to retrieve.
• Encounter-level links, such as encounter_content, provide access to content for the entire encounter.

Form filling sessions are not included in Ambient webhooks, even when they belong to the same encounter. Each Form filling session generates its own Form filling webhook.

​

Retrieve E/M codes, diagnoses, and Medication orders

Ambient webhooks include links to retrieve E/M codes, diagnoses, and Medication orders at both the session and encounter levels.

These links indicate where to request the data. They do not guarantee that the response contains values. The available data depends on the session configuration and the information available for the visit.

• E/M codes: Suki returns E/M codes only when you include artifacts: ["EM_CODES"] in the session creation request.
• Diagnoses: Suki returns diagnoses when they are available from the recorded visit or from the diagnoses you provide through Session context.
• Medication orders: Suki returns Medication orders when they are available from the recorded visit or from the Medication orders you provide through Session context.

When there is no data to return, the corresponding link still responds with HTTP 200 and an empty values list. Check the list before using the response in your application.

To generate E/M codes for an ambient visit, include artifacts: ["EM_CODES"] when creating the ambient session. Suki makes the resulting codes available through the Ambient webhook.

The separate E/M Coding webhook applies only to standalone E/M Coding sessions created without an ambient session. You do not need to use that webhook for E/M codes generated as part of an ambient session.

​

Webhook format

Suki configures the ambient webhook format on your partner account during onboarding. That setting applies only to ambient sessions. Form filling, standalone E/M Coding, and CKG ingestion each keep their own payload shape no matter which ambient format you use.

For ambient sessions, Suki supports these formats:

Format	What you receive	When to use it
Notification	A SUCCESS or FAILURE payload with session_id, encounter_id, and _links to retrieve the note and related results.	Recommended for new integrations. These docs and the Ambient API examples describe this format.
Canonical V1	An older ambient payload that includes note summary content and transcripts in the webhook body.	Existing partners already configured for this format.
FHIR	An ambient note submission payload with patient, encounter, document, and section content for FHIR-oriented write-back.	Existing partners already configured for this format.

If you are starting a new ambient integration, ask Suki to configure the notification format. If you are unsure which format your account already uses, or you need to change it, contact Suki support.

​

Next steps

Ambient payload reference - Every field in the success and failure payloads.

Retrieve ambient results - Turn webhook links into API calls.

Webhook request and response - Headers, the 200 response, and retries.

Ambient asynchronous notifications - OpenAPI specification and sample handlers.