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

# 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](/documentation/webhook/configuration), Suki sends a single <Badge color="blue" size="sm">POST</Badge> 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](/documentation/webhook/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.

<Columns cols={2}>
  <Card title="Ambient session completion" icon="check" href="/documentation/webhook/event-types#session-completion" />

  <Card title="Ambient session failure" icon="x" href="/documentation/webhook/event-types#session-failure" />

  <Card title="Ambient session timeout" icon="clock" href="/documentation/webhook/event-types#session-timeout" />

  <Card title="Ambient session cancellation" icon="ban" href="/documentation/webhook/event-types#session-cancellation" />

  <Card title="CKG data ingestion completion" icon="database" href="/documentation/webhook/event-types#ckg-data-ingestion-event-types" />
</Columns>

<Note>
  The [Asynchronous notifications (Webhook)](/api-reference/asynchronous/webhook.mdx) API reference currently provides example JSON for `success` and `failure` payloads. For `timeout` and `cancellation` webhook events, refer to this guide for payload details.
</Note>

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

<Accordion title="All Link Keys" defaultOpen={true}>
  <ResponseField name="contents" type="array">
    Session-level note content links.
  </ResponseField>

  <ResponseField name="encounter_content" type="array">
    Encounter-level content links.
  </ResponseField>

  <ResponseField name="structured_data" type="array">
    Session-level structured clinical data links.
  </ResponseField>

  <ResponseField name="encounter_structured_data" type="array">
    Encounter-level structured clinical data links.
  </ResponseField>

  <ResponseField name="status" type="array">
    Status check links.
  </ResponseField>

  <ResponseField name="transcripts" type="array">
    Transcript links.
  </ResponseField>
</Accordion>

### 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](/documentation/webhook/payload-and-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](/documentation/webhook/payload-and-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](/api-reference/ambient-content/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](/api-reference/ambient-content/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. |

<Note>
  Suki sends a webhook notification only when the ingestion job reaches a **terminal state**.
</Note>

For the complete payload schema and example requests, see [Payload & response](/documentation/webhook/payload-and-response).

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Payload & response](/documentation/webhook/payload-and-response) for payload structure, example JSON bodies, implementation tips, and follow-up API response codes.

<Icon icon="file-lines" iconType="solid" /> Refer to [Signature verification](/documentation/webhook/signature-verification) for HMAC-SHA-256 verification steps and Python and TypeScript examples.

<Icon icon="file-lines" iconType="solid" /> Refer to the [Asynchronous notifications (Webhook)](/api-reference/asynchronous/webhook.mdx) API reference for the OpenAPI specification and sample handler code.