status field to identify the payload type:
SUCCESS: Suki finished processing the session. This includes sessions where processing was skipped because the recording was silent or too short.FAILURE: Processing failed or the session was aborted.
_links object with links to retrieve session-level and encounter-level results. A failure payload contains an error code and description instead.
- For details about when Suki sends these notifications and how to handle each outcome, refer to Ambient webhook overview.
- For request headers, signature verification, and the response your endpoint must return, refer to Webhook request and response.
Success payload
Suki sends a success payload when ambient processing finishes. This includes cases where processing was skipped because the recording was silent or too short.The success payload always uses this notification shape.
- Every
_linkskey is present. - What each link returns depends on how you ran the session: the patient, visit, diagnoses, Medication orders, sections, and artifacts you seeded when you created or updated the session; whether you streamed live audio, uploaded a recording, or submitted a finished transcript; and what was available from the visit.
- Empty
valueslists are normal when that data was never produced. A dedicated guide for audio-file and transcript sessions is coming later.
Fields
string
required
Always
SUCCESS.string
required
Identifier of the ambient session that triggered this notification.
string
required
Identifier of the encounter associated with the ambient session.
array of strings
Identifiers of all ambient sessions in the encounter so far, ordered from oldest to newest. This list includes the session identified by
session_id.object
Additional context about the notification.
object
Links to the resources available for the encounter. Every key is present in the object. When a key has no links to return, its value is an empty array.Refer to The _links object for the complete list of keys and their descriptions.
Example success payload
This example shows an encounter containing two ambient sessions. Thesession_id identifies the second session in the sessions array. Session-level link arrays contain one link for each session, in the same order as the sessions array. Encounter-level link arrays contain one link for the entire encounter.
The _links object
The_links object contains the API paths your application can call to retrieve session and encounter results.
Each key contains an array of link objects. Every link object has the same four fields:
Session-level links
Session-level link arrays contain one link for each session insessions, in the same order.
Use the link’s name to identify the session whose results you want to retrieve.
Encounter-level links
Encounter-level link arrays contain one link for the entire encounter. These resources return encounter-level results rather than separate results for each session.Failure payload
Suki sends a failure payload when ambient processing fails or when a session is aborted. Unlike the success payload, the failure payload does not containsessions, _links, or additional_info. Instead, it includes an error code and a description of the error.
Fields
string
required
Always
FAILURE.string
required
Identifier of the ambient session that failed or was aborted.
string
required
Identifier of the encounter associated with the session.
string
required
Machine-readable code that identifies the reported error. Refer to Error codes.
string
required
Human-readable description of the error. This field can contain an empty string when Suki has no additional details.
Example failure payload
Error codes
Theerror_code field identifies the type of error reported in the failure notification.
Use
error_code to identify and handle error conditions in your application. Log error_detail to help with troubleshooting or to provide context when notifying your team or clinician.
Next steps
Retrieve ambient results - Build API requests from
_links and retrieve session and encounter results.
Ambient webhook overview - When Suki sends Ambient webhooks and how to handle each outcome.
Webhook event catalog - Payload references for other Suki products.
Ambient asynchronous notifications - OpenAPI specification and sample handlers.