> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> * For details about when Suki sends these notifications and how to handle each state, refer to [CKG ingestion webhook overview](https://developer.suki.ai/documentation/webhook/ckg-ingestion/overview.md).
> * For request headers, signature verification, and the response your endpoint must return, refer to [Webhook request and response](https://developer.suki.ai/documentation/webhook/payload-and-response.md).

## Payload fields

> [!NOTE]
>
> 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](https://developer.suki.ai/patient-summary-api-reference/ckg-data-ingestion/upload.md) 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.

**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.

**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

> [tab] COMPLETED
>
> When a FHIR push ingestion job completes successfully, Suki sends a payload that can look like the following:
>
> ```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> {
>   "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"
>   }
> }
> ```

> [tab] FAILED
>
> When a FHIR push ingestion job fails during processing, Suki sends a payload that can look like the following:
>
> ```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> {
>   "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"
>   }
> }
> ```

> [tab] 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:
>
> ```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> {
>   "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](https://developer.suki.ai/documentation/webhook/ckg-ingestion/handle-results.md)** - What to do for each state.

 **[CKG ingestion webhook overview](https://developer.suki.ai/documentation/webhook/ckg-ingestion/overview.md)** - When Suki sends CKG ingestion webhooks and how to handle each state.

 **[Webhook event catalog](https://developer.suki.ai/documentation/webhook/event-catalog.md)** - Payload references for other Suki products.

 **[CKG ingestion asynchronous notifications](https://developer.suki.ai/patient-summary-api-reference/asynchronous/webhook.md)** - OpenAPI specification and sample handlers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.