CKG Ingestion Webhook Overview

Understand when Suki sends CKG ingestion webhooks after a FHIR push upload, and what COMPLETED, FAILED, and ABORTED mean

CKG ingestion webhooks notify your application when Suki finishes loading a FHIR bundle into the Clinical Knowledge Graph (CKG). Your application can use the notification to know when patient data is ready for Patient Summary generation without repeatedly polling the API.

During partner onboarding, Suki configures a callback URL for your account. Suki sends notifications to this URL when an ingestion job completes, fails, or is aborted.

Unlike the other webhooks, this one includes the full result, including any error details. There are no links to follow.

CKG ingestion uses the same callback URL, signature, and delivery rules as every other Suki webhook. Its payload is different, though: it has its own shape, and that shape does not change with the webhook format configured for your partner account.

​

Common use cases

Use the CKG ingestion webhook when you want your application to react as soon as a FHIR push upload finishes ingestion, instead of polling for status.

Generate Patient Summaries

When the notification reports COMPLETED, start Patient Summary generation for the encounters in the uploaded bundle.

Sync Clinical Systems

Update your EHR, EMR, or other clinical systems when new patient data is available in CKG.

Notify Clinicians

Tell clinicians or care teams that updated patient data is available.

Retry or Investigate Failures

When the notification reports FAILED or ABORTED, use the error object to decide whether to upload again or fix the bundle first.

​

When Suki sends a CKG ingestion webhook

Suki sends a CKG ingestion webhook after you upload a bundle with the CKG Data Ingestion APIs and the ingestion job reaches a final state. Suki does not send a webhook while the job is waiting for the upload or while it is running.

The top-level state indicates the outcome reported by the notification:

state	What happened	Matching polling status	What your application should do
COMPLETED	The FHIR data was ingested into CKG.	COMPLETED	Generate Patient Summaries for the encounters in the bundle.
FAILED	Ingestion failed during processing.	FAILED	Read the error object, fix the bundle if needed, and upload again.
ABORTED	Ingestion stopped before it finished, for example because the upload URL expired before the bundle was uploaded.	ARCHIVED	Request a new upload URL and upload the bundle again.

The matching polling status is what Check ingestion status returns for the same job. The webhook reports an archived upload as ABORTED, so you can tell an expired upload apart from a processing failure.

​

Delivery rules

Your webhook receiver must account for the following behaviors:

• Uploads you never finish still generate webhooks. When the upload URL expires before you upload the bundle, Suki ends the job and sends an ABORTED webhook for it.
• The same notification can be delivered more than once. Use transaction_id and state to identify and skip notifications your application has already processed.

Start Patient Summary generation only after a COMPLETED webhook or a COMPLETED response from Check ingestion status.

If you suspect that you missed a notification, call the same endpoint with the transaction_id to check the job’s current status.

For delivery behavior shared by all Suki webhooks, refer to Delivery rules.

​

How a CKG ingestion webhook works

The following sequence shows how Suki delivers a notification and how your application acts on the result.

1. Request an Upload URL

   Call Request FHIR bundle upload URL with your organization_id, and optionally a correlation_id. Save the transaction_id from the response.

2. Upload the FHIR Bundle

   Upload the bundle to the upload URL from the previous step within 15 minutes.

3. Suki Ingests the Data

   Suki processes the bundle and loads the data into CKG.

4. Suki Sends the Webhook

   Suki sends a POST request to your configured callback URL. The request contains the state and the transaction_id.

5. Verify the Request and Respond

   Your endpoint verifies the webhook signature and returns HTTP 200 within 30 seconds. Refer to Signature verification.

6. Act on the State

   Match the transaction_id to your upload, then generate summaries or upload again. Refer to Handle CKG ingestion results.

​

What makes this payload different

The CKG ingestion payload does not follow the status pattern that Ambient, Form filling, and E/M Coding use:

• The outcome is in state, not status. A CKG payload never has a status field.
• There is no session_id or encounter_id. Use transaction_id to match the notification to your upload.
• There are no _links. Everything you need, including error details, is in the payload itself.
• additional_info.session_type is always CKG_INGESTION, whether the job completed, failed, or was aborted.

​

Next steps

CKG ingestion payload reference - Every field in the payload and the error object.

Handle CKG ingestion results - What to do for each state.

Integrate CKG - Why CKG is required and how ingestion works.

CKG Data Ingestion APIs - Upload URL, upload, and status endpoints.