Webhook Event Types

Event types your Webhook endpoint receives when Ambient sessions complete, fail, time out, or are cancelled

Suki sends webhook notifications to your configured callback URL Ambient session events and CKG data ingestion events. After you configure a callback URL during Partner onboarding, Suki sends a single POST request whenever one of these events occurs.

Each webhook request uses Content-Type: application/json and includes the generated-at and X-API-Key headers. Verify these headers before processing the request. For more information, refer to Signature verification guide.

The request body varies by event type:

• Ambient session webhooks include a top-level status field that identifies the session outcome.
• CKG ingestion webhooks include transaction_id, correlation_id, and state fields that identify the ingestion job and its status.

The following sections describe each webhook event and its payload.

Ambient session completion

Ambient session failure

Ambient session timeout

Ambient session cancellation

CKG data ingestion completion

The Asynchronous notifications (Webhook) API reference currently provides example JSON for success and failure payloads. For timeout and cancellation webhook events, refer to this guide for payload details.

Session completion

When an Ambient session finishes and note generation completes successfully, your endpoint receives a session completion notification.

When status is "success": The payload identifies the session and encounter and provides links to retrieve results. It includes:

• session_id, encounter_id (always present).
• Optionally: sessions, additional_info, _links.

Inside _links, each key is an array of link objects (href, method, name, type).

These are the keys you will see in the _links object:

All Link Keys

contents · array

Session-level note content links.

encounter_content · array

Encounter-level content links.

structured_data · array

Session-level structured clinical data links.

encounter_structured_data · array

Encounter-level structured clinical data links.

status · array

Status check links.

transcripts · array

Transcript links.

Link keys usage

Use the _links object to fetch session content, encounter content, structured clinical data, status, and transcripts from the Ambient APIs. For each link, combine its href with your API base URL and use the correct authentication when you call those follow-up APIs.

The sessions array lists the session IDs tied to the encounter so far.

For an example JSON body, refer to Payload & response.

Session failure

When the Ambient session or note generation fails, your endpoint receives a session failure notification.

When status is "failure": The payload identifies the session and encounter and describes the error. It includes:

• session_id, encounter_id, error_code, error_detail.

Use error_code and error_detail to log the failure, trigger alerts, or show an error in your application. The API reference example uses ERROR_CODE_TRANSCRIPTION with detail Error in transcription.

For an example JSON body, refer to Payload & response.

Session timeout

When an Ambient session times out, your endpoint receives a session timeout notification.

The payload includes session_id and encounter_id. The API reference does not yet document other fields or example JSON for this event.

Record the identifiers and update your application state. If you need the current processing state, refer to Ambient session status.

Session cancellation

When an Ambient session is cancelled, your endpoint receives a session cancellation notification.

The payload includes session_id and encounter_id. The API reference does not yet document other fields or example JSON for this event.

Record the identifiers and update any in-progress state for that session. To confirm how the session ended on the platform, refer to Ambient session status. Documented status values there include aborted, which means the Ambient session was cancelled by the user or client.

CKG data ingestion event types

The state field indicates the outcome of the FHIR data ingestion job and can have one of the following values:

state	Description
COMPLETED	The FHIR data was successfully ingested into the Clinical Knowledge Graph (CKG).
FAILED	The ingestion job failed during processing. The payload includes an error object with additional details.
ABORTED	The ingestion job was aborted before processing completed, for example, because the upload expired before it was finalized. The payload may include an error object.

Suki sends a webhook notification only when the ingestion job reaches a terminal state.

For the complete payload schema and example requests, see Payload & response.

Next steps

Refer to Payload & response for payload structure, example JSON bodies, implementation tips, and follow-up API response codes.

Refer to Signature verification for HMAC-SHA-256 verification steps and Python and TypeScript examples.

Refer to the Asynchronous notifications (Webhook) API reference for the OpenAPI specification and sample handler code.