Webhook Event Types

Event types your Webhook endpoint receives when Ambient or Form filling sessions complete or fail, and when CKG ingestion finishes

Suki sends webhook notifications to your configured callback URL for Ambient session events, Form filling 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 the Signature verification guide.

The request body varies by event type:

• Ambient and Form filling webhooks include a top-level status field. The value is SUCCESS or FAILURE.
• CKG ingestion webhooks include transaction_id, correlation_id, and state fields that identify the ingestion job and its status.

If the same endpoint receives more than one product, check additional_info.session_type. Values include AMBIENT, FORM_FILLING, and CKG_INGESTION.

The following sections describe each webhook event and its payload. To search or filter every payload in one place, use the Event catalog.

Ambient Session Completion

Ambient Session Failure

CKG Data Ingestion Completion

Suki does not send separate timeout or cancellation webhooks. If a session fails or is aborted, you get status: FAILURE. If processing finishes, you get status: SUCCESS. For Ambient sessions, that SUCCESS can still arrive when the recording was silent or too short and session status is skipped, so confirm status before you treat the visit as note-ready.

Session completion

When an Ambient session finishes processing, your endpoint receives a session completion notification with status: SUCCESS. Form filling uses the same SUCCESS payload shape. Treat Ambient SUCCESS as a signal that processing finished, then check Session status before you fetch content or open note review. Open the note only when status is completed. If status is skipped, the transcript was empty or the audio was too short, so there is no note this time. Offer the clinician a chance to record again rather than showing an empty chart. For the full status flow in your product UI, refer to Check note status.

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 for Ambient:

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.

section_structured_data · array

Session-level section structured data links. Learn more in Embedded Forms.

encounter_section_structured_data · array

Encounter-level section structured data links. Follow them to read filled Embedded Form values from the latest completed session for the encounter.

status · array

Status check links.

transcripts · array

Transcript links.

For Form filling, the links you use are mainly structured_data and status. Other _links arrays are usually empty.

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, or when the session is aborted, your endpoint receives a session failure notification. Form filling failures use the same FAILURE payload shape.

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. Known codes include ERROR_CODE_UNSPECIFIED and ERROR_CODE_NOTIFICATION_GENERATION_FAILURE.

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

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

Event catalog - Search every webhook payload and status or state value.

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

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

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