Skip to main content
When Suki sends a Webhook notification, it makes an HTTP POST request to your configured callback URL with the following header:
HTTP

​
Request headers

Before processing an HTTP POST request body, verify that the request originated from Suki by validating the following request headers:

​
How to handle the request

After verifying the request headers:
  1. Parse the JSON request body.
  2. Read the top-level status (or state for CKG ingestion) field.
  3. Process the notification based on that value (SUCCESS or FAILURE for Ambient and Form filling, or COMPLETED, FAILED, or ABORTED for CKG ingestion).
  4. On success, use the _links object (if present) to retrieve medical form output, note content, and session status. For Ambient, confirm session status is completed before you treat content as ready.
  5. Use session_id or transaction_id as your deduplication key.
For the complete request specification and example implementations in Python and TypeScript, see the Asynchronous notifications (Webhook) API reference or Form filling asynchronous notifications.

​
Notification payloads

Every notification includes a top-level field indicating its status or state. The remaining fields depend on its value.
Every Ambient notification includes a top-level status field. The remaining fields depend on its value.

​
Success payload

When status is SUCCESS, the payload identifies the session and encounter and provides links so you can retrieve note content, transcripts, and related resources. Treat Ambient SUCCESS as a signal that processing finished, then confirm Session status is completed before you open note review. Empty or silent recordings can return this webhook when status is skipped and there is no note. See Check note status.A success payload can look like the following:

​
Required fields

​
Optional fields

​
The _links object

The _links object contains one or more collections of resource links. Each link object includes:The following link collections can be included:

Available link collections

To retrieve generated resources, combine each href value with your API base URL and call the corresponding endpoint using the specified HTTP method and appropriate authentication.If present, the sessions array lists every Ambient session currently associated with the encounter.

​
Failure payload

When status is FAILURE, the payload identifies the session and describes why processing failed or was aborted.Use these fields to determine why the request failed and decide whether to retry, alert, or surface the error to users.For a summary of Ambient and Form filling notification events, see Event types.

​
Example payloads

The following examples show the request body your callback URL receives for successful and failed notifications.

​
Success payload

When an Ambient session completes successfully, Suki sends a payload that can look like the following:
Use the links in _links to retrieve note content, structured data, transcripts, or session status. Combine each href with your API base URL and authenticate before you call the endpoint.If present, the sessions array lists every Ambient session currently associated with the encounter.

​
Failure payload

When an Ambient session fails or is aborted, Suki sends a payload that can look like the following:
Use error_code and error_detail to log the failure, alert, or show an error to users.

​
Common use cases

Use Webhook notifications to detect when a session or ingestion job completes or fails and trigger automated workflows.

Ambient Sessions

Use Ambient session completion or failure notifications to automate downstream workflows:
  • Synchronize completed clinical notes with your EHR or EMR.
  • Trigger downstream workflows such as coding, billing, or document processing.
  • Notify clinicians or care teams when a session completes or requires attention.
  • Start custom workflows based on the session status.

Form Filling Sessions

Use Form filling webhook notifications to detect when a medical form session has completed or failed and trigger automated workflows:
  • Update EHR or EMR records with generated form data.
  • Notify clinicians that structured assessment forms are ready for review.
  • Trigger downstream analytics or quality workflows on completed forms.
  • Update application state after a successful Form filling session.
  • Surface or retry failed form generation based on error_code and error_detail.

CKG Ingestion

Use CKG ingestion notifications to detect when a FHIR push ingestion job has completed or failed and trigger automated workflows:
  • Update patient records in your EHR or EMR.
  • Notify clinicians or care teams that new patient data is available.
  • Trigger downstream analytics or reporting workflows.
  • Update application state after a successful ingestion.
  • Retry failed ingestion jobs when appropriate.

​
Implementation recommendations

Follow these practices when implementing your callback URL to receive notifications for Ambient session, Form filling, and CKG data ingestion events:
  1. Verify the request signature before processing the payload. See Signature verification.
  2. Validate the generated-at timestamp to reject stale requests.
  3. Process notifications asynchronously and return a 2xx response as quickly as possible.
  4. Treat notifications as idempotent by using session_id or transaction_id as the deduplication key.
  5. Store your webhook secret securely in a secrets manager.
  6. Log request metadata instead of full payloads whenever possible.
  7. Protect the endpoint with rate limiting and high availability.
  8. Fetch structured output from the _links.structured_data endpoint rather than expecting inline form data in the webhook body.
  9. Handle non_generated_values in the structured data response to identify templates that were requested but not filled.

​
Responses from linked API endpoints

After receiving a success Webhook, call the linked endpoints to retrieve generated output.
When you call one of the resource URLs returned in the _links object, the Ambient APIs return standard HTTP status codes.
Handle 401 by re-authenticating or refreshing the token. Handle 400 by fixing the request or showing an error. Consider retrying on 5xx when appropriate.
Last modified on October 16, 2026