CKG Ingestion Webhook Payload & Response

Reference for the CKG data ingestion webhook payload, including state values, field definitions, and the error object

When a FHIR push ingestion job reaches a final state, Suki sends one payload to your configured callback URL. The same payload shape covers all three outcomes.

Read the top-level state field to identify the outcome:

• COMPLETED: The FHIR data was ingested into CKG.
• FAILED: Ingestion failed during processing.
• ABORTED: Ingestion stopped before it finished, for example because the upload URL expired before the bundle was uploaded.

Unlike Ambient, Form filling, and E/M Coding webhooks, this payload includes the full result in the body. There are no _links. When ingestion did not complete, read the error object if Suki recorded one.

• For details about when Suki sends these notifications and how to handle each state, refer to CKG ingestion webhook overview.
• For request headers, signature verification, and the response your endpoint must return, refer to Webhook request and response.

​

Payload fields

This payload always uses this CKG shape.

• It does not use status, session_id, encounter_id, or _links.
• The shape does not change with the ambient webhook format configured for your partner account.
• If your handler checks status first, check for state before it so CKG notifications are not dropped.
• The error object appears only when state is FAILED or ABORTED, and only when Suki recorded an error for the job. Do not assume it is always present.

​

Fields

transaction_id · string · required

Identifier returned by Request FHIR bundle upload URL when you started the upload. Use it to match the notification to your upload.

organization_id · string · required

Partner-facing organization identifier. This is the same organization_id you passed when you requested the upload URL. It is not an internal Suki organization ID.

correlation_id · string · required

Correlation ID for the upload. If you did not send one when you requested the upload URL, Suki generated it for you.

state · string · required

Final state of the ingestion job: COMPLETED, FAILED, or ABORTED.

created_at · string (date and time)

When the ingestion job was created, in UTC, for example 2026-07-09T10:12:43Z. Suki leaves this field out when the time is unavailable.

completed_at · string (date and time)

When the ingestion job reached its final state, in UTC, for example 2026-07-09T10:13:11Z. Suki leaves this field out when the time is unavailable.

error · object

Details about why ingestion did not complete. It appears only when state is FAILED or ABORTED, and only when Suki recorded an error for the job.

Show properties

code · string

Machine-readable error code, for example BUNDLE_PARSE_ERROR or UPLOAD_ABORTED.

message · string

Human-readable description of the error.

retryable · boolean

true when uploading the bundle again may succeed. false when you need to fix the bundle or the request first.

additional_info · object · required

Additional context about the notification.

Show properties

session_type · string

Always CKG_INGESTION, whether the job completed, failed, or was aborted. Use this field to identify the product when multiple Suki products send notifications to the same callback URL.

​

Example payloads

COMPLETED

When a FHIR push ingestion job completes successfully, Suki sends a payload that can look like the following:

{
  "transaction_id": "46b88f6d-...",
  "organization_id": "your-org-id",
  "correlation_id": "2e3a1724-...",
  "state": "COMPLETED",
  "created_at": "2026-07-09T10:12:43Z",
  "completed_at": "2026-07-09T10:13:11Z",
  "additional_info": {
    "session_type": "CKG_INGESTION"
  }
}

FAILED

When a FHIR push ingestion job fails during processing, Suki sends a payload that can look like the following:

{
  "transaction_id": "46b88f6d-...",
  "organization_id": "your-org-id",
  "correlation_id": "2e3a1724-...",
  "state": "FAILED",
  "created_at": "2026-07-09T10:12:43Z",
  "completed_at": "2026-07-09T10:13:11Z",
  "error": {
    "code": "BUNDLE_PARSE_ERROR",
    "message": "invalid bundle",
    "retryable": false
  },
  "additional_info": {
    "session_type": "CKG_INGESTION"
  }
}

ABORTED

When ingestion is aborted, for example because the upload URL expired before the bundle was uploaded, Suki sends a payload that can look like the following:

{
  "transaction_id": "46b88f6d-...",
  "organization_id": "your-org-id",
  "correlation_id": "2e3a1724-...",
  "state": "ABORTED",
  "created_at": "2026-07-09T10:12:43Z",
  "completed_at": "2026-07-09T10:13:11Z",
  "error": {
    "code": "UPLOAD_ABORTED",
    "message": "Upload was not received within the allowed window.",
    "retryable": true
  },
  "additional_info": {
    "session_type": "CKG_INGESTION"
  }
}

​

Next steps

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

CKG ingestion webhook overview - When Suki sends CKG ingestion webhooks and how to handle each state.

Webhook event catalog - Payload references for other Suki products.

CKG ingestion asynchronous notifications - OpenAPI specification and sample handlers.