SUCCESS Ambient webhook, the payload includes links to the session status, note, transcript, structured data, and other results for that encounter.
The webhook does not contain the generated note or other result bodies. Your application must call the linked Ambient API endpoints to retrieve them.
status link for the session in the notification. Load the note with contents only when that status is completed. Pull the transcript, structured data, E/M codes, diagnoses, or Medication orders the same way when your product needs them.
Each href is relative to /api/v1/ambient. Join your Ambient API base URL with that path, and authenticate the request with your Suki Token.
Prerequisites
Before you retrieve results, make sure you have:- A webhook receiver: An endpoint that receives Suki webhooks and verifies their signatures. Refer to Webhook quickstart and Signature verification.
- A valid Suki Token: Authenticate Ambient API requests with the
sdp_suki_tokenheader. Include thesdp_provider_idheader when your partnership requires it. Refer to Ambient API quickstart.
Build the full URL
Eachhref in an Ambient webhook link is relative to the Ambient API path, /api/v1/ambient. Append /api/v1/ambient and the href to your API base URL to build the full request URL.
For example, when the production base URL is https://sdp.suki.ai and the link contains:
https://sdp.suki-stage.com as the API base URL.
Available endpoints
This table maps each_links key to its Ambient API endpoint and API reference page.
Every link object includes a
method field. Use that method when you call the endpoint. For the links in this table, the method is always GET.
Diagnoses and Medication orders are Ambient API results. The published API reference documents them on the session and encounter structured data pages. The webhook also includes dedicated
diagnoses and orders links. Call those href values when you only need that slice, or call structured_data / encounter_structured_data when you want the full structured data response documented in the API reference.Retrieve results step by step
Follow this sequence after your webhook endpoint receives aSUCCESS notification:
Verify the Webhook and Return HTTP 200
Verify the webhook signature and return HTTP 200 within 30 seconds. Do not wait for Ambient API calls to finish before you respond. Process the notification and retrieve results in a background job.
Select the Correct Links
-
Read
_linksand select the keys you need. -
Session-level arrays contain one link for each session in the encounter. Match the link’s
nameto the webhook’ssession_idwhen you want results for the session that triggered the notification. - Encounter-level arrays contain one link for the entire encounter.
Check the Session Status
-
Call the
statuslink for the current session. Retrieve the note and other content only when the returned status iscompleted. -
If the status is
skipped, Suki did not generate a note for that session. Skip the content requests and offer the clinician a chance to record again. -
Do not treat every non-
completedstatus asskipped. Handlefailed,aborted, and in-progress values according to the status API response. Refer to Track note generation status.
Retrieve the Required Results
-
Call
contentsfor the selected session’s note. Useencounter_contentwhen your application needs the combined encounter note. - Call the transcript, structured data, E/M codes, diagnoses, and Medication orders links only when your application needs those results.
A link in
_links does not guarantee that the response contains values. em_codes, diagnoses, and orders can return HTTP 200 with an empty values list. Refer to Retrieve E/M codes, diagnoses, and Medication orders.Example: retrieve one session note
The following examples retrieve the note for the session that triggered the webhook. Keep this path focused onstatus and contents. The endpoint table above lists every other key.
Run this code after your webhook endpoint has verified the signature and returned HTTP 200. The examples:
- Read
session_idand_linksfrom the webhook payload. - Find the
statuslink for that session. - Continue only when the session status is
completed. - Retrieve the session note through the
contentslink.
Code example
- Python
- TypeScript
- Go
Example: retrieve other results
After status iscompleted, reuse the same base URL, Ambient path, headers, and helper. Change only the _links key.
Session transcript
Matchname to session_id, the same way you select contents.
Code example
- Python
- TypeScript
- Go
Encounter note content
Encounter-level arrays hold a single link. Use the first entry. Do not match onsession_id.
Code example
- Python
- TypeScript
- Go
structured_data, em_codes, diagnoses, orders, and the other encounter-level keys in the endpoint table.
Responses from linked endpoints
When you call a linked Ambient API endpoint, Suki returns standard HTTP status codes.400 Bad Request: Fix the URL or request parameters, then send the request again.401 Unauthorized: Log in again for a new Suki Token, then retry with the updated token.5xx Server Error: Retry the request after a short delay.