> ## Documentation Index > Fetch the complete documentation index at: https://developer.suki.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ambient Webhook Overview > Understand when Suki sends Ambient webhooks, how to interpret session outcomes, and how to retrieve the results Quick summary Suki exposes an Ambient webhook to notify your application when an ambient session reaches a final processing outcome. The top-level `status` is `SUCCESS` or `FAILURE`. A successful notification identifies the session as `AMBIENT` in `additional_info.session_type` and provides `_links` to retrieve the note, transcript, structured data, E/M codes, diagnoses, and orders. Last updated: November 2026 Ambient webhooks notify your application when Suki finishes processing an ambient session (A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations.). 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 (An endpoint URL registered by a partner to receive webhook event notifications from Suki, such as session completion or note generation events.) 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. > [card] 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. > [card] 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. > [card] 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. > [card] 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. | > [!TIP] > > `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 (One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit.) 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](https://developer.suki.ai/api-reference/ambient-content/status.md) and retrieve the note only when the status is `completed`. > [!NOTE] > > If you cancelled a session or suspect that you missed a notification, call the same endpoint to check the session's current status. > [!TIP] > > For delivery behavior shared by all Suki webhooks, refer to [Delivery rules](https://developer.suki.ai/documentation/webhook/event-types.md#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](https://developer.suki.ai/documentation/webhook/signature-verification.md). **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](https://developer.suki.ai/documentation/webhook/ambient/retrieve-results.md). ## 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](https://developer.suki.ai/api-reference/ambient-content/status.md). **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](https://developer.suki.ai/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status.md). ## 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](https://developer.suki.ai/documentation/webhook/form-filling/overview.md). ## Retrieve E/M codes, diagnoses, and Medication orders Ambient webhooks include links to retrieve E/M codes (Evaluation and Management coding. After a visit, Suki reads the note and recommends the visit code billing uses, with a short reason. You can ask for codes with an ambient visit, or send a finished note on its own.), 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](https://developer.suki.ai/api-reference/ambient-sessions/context.md). * **Medication orders:** Suki returns Medication orders when they are available from the recorded visit or from the Medication orders you provide through [Session context](https://developer.suki.ai/api-reference/ambient-sessions/context.md). 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](https://developer.suki.ai/documentation/webhook/em-coding/overview.md) 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](mailto:support@suki.ai). ## Next steps **[Ambient payload reference](https://developer.suki.ai/documentation/webhook/ambient/payload.md)** - Every field in the success and failure payloads. **[Retrieve ambient results](https://developer.suki.ai/documentation/webhook/ambient/retrieve-results.md)** - Turn webhook links into API calls. **[Webhook request and response](https://developer.suki.ai/documentation/webhook/payload-and-response.md)** - Headers, the 200 response, and retries. **[Ambient asynchronous notifications](https://developer.suki.ai/api-reference/asynchronous/webhook.md)** - OpenAPI specification and sample handlers. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.