> ## 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 endpoint when any ambient session completes, fails, times out, or cancelled. Refer to the following sections to understand the different event types and how to handle them.

After you configure a callback URL during [Partner onboarding](/documentation/webhook/configuration), Suki sends a single <Badge color="blue" size="sm">POST</Badge> to that URL when an ambient session completes, fails, times out, or is cancelled. Each delivery uses **`Content-Type: application/json`** and includes **`generated-at`** and **`X-API-Key`** headers so you can verify the request before you trust the body. Refer to [Signature verification](/documentation/webhook/signature-verification) for those steps.

Read the top-level **`status`** field in the JSON and branch your handler on the event type. For **session completion** and **session failure**, the API reference documents **`"success"`** and **`"failure"`** payloads with example JSON. For **session timeout** and **session cancellation**, the payload includes **`session_id`** and **`encounter_id`**; refer to the sections below for what to do next.

Use the following event types to handle the notifications based on the event type:

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

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

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

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

<Note>
  The [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference documents **`success`** and **`failure`** payloads with example JSON. Timeout and cancellation are webhook events listed in this guide; the API reference does not yet include example JSON for those events.
</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.

## 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) API reference for the OpenAPI specification and sample handler code.