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

# Ambient Webhook Payload & Response

> Reference for Ambient webhook success and failure payloads, including field definitions, error codes, and every _links key

When an ambient session reaches a final processing outcome, Suki sends a success or failure payload to your configured callback URL.

Read the top-level `status` field to identify the payload type:

* `SUCCESS`: Suki finished processing the session. This includes sessions where processing was skipped because the recording was silent or too short.
* `FAILURE`: Processing failed or the session was aborted.

Each payload contains the session and encounter identifiers. A success payload also contains an `_links` object with links to retrieve session-level and encounter-level results. A failure payload contains an error code and description instead.

> [!NOTE]
>
> * For details about when Suki sends these notifications and how to handle each outcome, refer to [Ambient webhook overview](https://developer.suki.ai/documentation/webhook/ambient/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).

## Success payload

Suki sends a success payload when ambient processing finishes. This includes cases where processing was skipped because the recording was silent or too short.

> [!NOTE]
>
> The success payload **always uses this notification shape**.
>
> * Every `_links` key is present.
> * What each link returns depends on how you ran the session: the patient, visit, diagnoses, Medication orders, sections, and artifacts you seeded when you created or updated the session; whether you streamed live audio, uploaded a recording, or submitted a finished transcript; and what was available from the visit.
> * Empty `values` lists are normal when that data was never produced. A dedicated guide for audio-file and transcript sessions is coming later.

### Fields

**status** `string` *required*

Always `SUCCESS`.

**session\_id** `string` *required*

Identifier of the ambient session that triggered this notification.

**encounter\_id** `string` *required*

Identifier of the encounter associated with the ambient session.

**sessions** `array of strings`

Identifiers of all ambient sessions in the encounter so far, ordered from oldest to newest. This list includes the session identified by `session_id`.

**additional\_info** `object`

Additional context about the notification.

**properties**

**session\_type** `string`

Always `AMBIENT` in an Ambient success payload. Use this field to identify the product when multiple Suki products send notifications to the same callback URL.

**practice\_id** `string`

Partner-facing practice identifier. Suki includes this field only when it can resolve the practice associated with the session.

**\_links** `object`

Links to the resources available for the encounter. Every key is present in the object. When a key has no links to return, its value is an empty array.

Refer to [The \_links object](#the-_links-object) for the complete list of keys and their descriptions.

### Example success payload

This example shows an encounter containing two ambient sessions. The `session_id` identifies the second session in the `sessions` array. Session-level link arrays contain one link for each session, in the same order as the `sessions` array. Encounter-level link arrays contain one link for the entire encounter.

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "SUCCESS",
  "session_id": "29de56bc-960a-4cd5-b18f-79a798d62874",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "sessions": [
    "20965414-929a-4f71-a3e5-b92bec07d086",
    "29de56bc-960a-4cd5-b18f-79a798d62874"
  ],
  "additional_info": {
    "session_type": "AMBIENT",
    "practice_id": "your-practice-id"
  },
  "_links": {
    "status": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/status",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/status",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "contents": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/content",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/content",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "transcripts": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/transcript",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/transcript",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "structured_data": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/structured-data",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "section_structured_data": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/structured-data/section-structured-data",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data/section-structured-data",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "em_codes": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/structured-data/em-codes",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data/em-codes",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "diagnoses": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/structured-data/diagnoses",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data/diagnoses",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "orders": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/structured-data/orders",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      },
      {
        "href": "/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data/orders",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ],
    "encounter_content": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/content",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "encounter_structured_data": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/structured-data",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "encounter_section_structured_data": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/structured-data/section-structured-data",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "encounter_em_codes": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/structured-data/em-codes",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "encounter_diagnoses": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/structured-data/diagnoses",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "encounter_orders": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/structured-data/orders",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ]
  }
}
```

## The \_links object

The `_links` object contains the API paths your application can call to retrieve session and encounter results.

Each key contains an array of link objects. Every link object has the same four fields:

| Field | Description |
| :- | :- |
| `href` | Resource path relative to the Ambient API path. Refer to [Build the full URL](https://developer.suki.ai/documentation/webhook/ambient/retrieve-results.md#build-the-full-url) for how to construct the complete request URL. |
| `method` | HTTP method for the request. Always `GET`. |
| `name` | Session ID or encounter ID associated with the resource. Use this field to identify the link for a specific session or encounter. |
| `type` | Response media type. Always `application/json`. |

### Session-level links

Session-level link arrays contain one link for each session in `sessions`, in the same order.

Use the link's `name` to identify the session whose results you want to retrieve.

| Key | Description |
| :- | :- |
| `status` | Current processing status of the session, such as `completed` or `skipped`. |
| `contents` | Note content generated for that session. It contains only that session's content, not content from earlier sessions in the encounter. |
| `transcripts` | Transcript generated for that session. |
| `structured_data` | Structured clinical data generated for that session. |
| `section_structured_data` | Section-level structured data for that session, including filled [Embedded Form](https://developer.suki.ai/documentation/concepts/ambient-clinical-notes/embedded-forms.md) values. |
| `em_codes` | Recommended E/M codes for that session. The response contains an empty `values` list unless the session was created with `artifacts: ["EM_CODES"]`. |
| `diagnoses` | Diagnoses associated with that session. The response contains an empty `values` list when the visit has no diagnoses from the recording or the session context you provided. |
| `orders` | Medication orders associated with that session. The response contains an empty `values` list when the visit has no Medication orders from the recording or the session context you provided. |

### Encounter-level links

Encounter-level link arrays contain one link for the entire encounter.

These resources return encounter-level results rather than separate results for each session.

| Key | Description |
| :- | :- |
| `encounter_content` | Combined note content for the encounter, through the latest successful ambient session. |
| `encounter_structured_data` | Structured clinical data from the latest successful ambient session in the encounter. |
| `encounter_section_structured_data` | Section-level structured data from the latest successful ambient session in the encounter. |
| `encounter_em_codes` | E/M codes from the latest successful ambient session in the encounter. |
| `encounter_diagnoses` | Diagnoses from the latest successful ambient session in the encounter. |
| `encounter_orders` | Medication orders from the latest successful ambient session in the encounter. |

> [!TIP]
>
> Make your webhook parser ignore unrecognized keys in `_links`. This allows your integration to handle new link types added in future releases without breaking the webhook handler.

## Failure payload

Suki sends a failure payload when ambient processing fails or when a session is aborted.

Unlike the success payload, the failure payload does not contain `sessions`, `_links`, or `additional_info`. Instead, it includes an error code and a description of the error.

### Fields

**status** `string` *required*

Always `FAILURE`.

**session\_id** `string` *required*

Identifier of the ambient session that failed or was aborted.

**encounter\_id** `string` *required*

Identifier of the encounter associated with the session.

**error\_code** `string` *required*

Machine-readable code that identifies the reported error. Refer to [Error codes](#error-codes).

**error\_detail** `string` *required*

Human-readable description of the error. This field can contain an empty string when Suki has no additional details.

### Example failure payload

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "FAILURE",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "error_code": "ERROR_CODE_UNSPECIFIED",
  "error_detail": "Error in transcription"
}
```

> [!WARNING]
>
> A failure payload does not contain `additional_info`, so it does not identify the product through `session_type`.
>
> If multiple Suki products send notifications to the same callback URL, match `session_id` against the ambient session IDs your application saved when it created the sessions.

### Error codes

The `error_code` field identifies the type of error reported in the failure notification.

| `error_code` | Description |
| :- | :- |
| `ERROR_CODE_UNSPECIFIED` | Processing failed or the session was aborted. Check `error_detail` for the reported reason. |
| `ERROR_CODE_NOTIFICATION_GENERATION_FAILURE` | Suki could not prepare the webhook body for the session. In this case, `error_detail` is `Error Preparing Webhook Notification`. Call [Get ambient session status](https://developer.suki.ai/api-reference/ambient-content/status.md) to determine the actual session outcome. |

Use `error_code` to identify and handle error conditions in your application. Log `error_detail` to help with troubleshooting or to provide context when notifying your team or clinician.

> [!WARNING]
>
> Do not use `error_detail` as the basis for application logic. Its wording can change. Use `error_code` for programmatic error handling.

## Next steps

 **[Retrieve ambient results](https://developer.suki.ai/documentation/webhook/ambient/retrieve-results.md)** - Build API requests from `_links` and retrieve session and encounter results.

 **[Ambient webhook overview](https://developer.suki.ai/documentation/webhook/ambient/overview.md)** - When Suki sends Ambient webhooks and how to handle each outcome.

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

 **[Ambient asynchronous notifications](https://developer.suki.ai/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.