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

> Search Ambient, Form filling, and CKG webhook payloads by status and state

export const WhFilterChevron = () => <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
    <path d="m6 9 6 6 6-6" />
  </svg>;

export const WhSearchIcon = () => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
    <path fill="none" d="M11 17.5a6.5 6.5 0 1 0 0-13 6.5 6.5 0 0 0 0 13z" />
    <path d="m21 21-4.3-4.3" />
  </svg>;

Use this catalog to find the webhook your endpoint handles. Search by status, state, or field name, or filter by product. Open a card for the example JSON body Suki posts to your callback URL.

Suki does not send named events such as `session.created` or `note.generated`. Ambient and Form filling notifications use a top-level **`status`** of **`SUCCESS`** or **`FAILURE`**. CKG ingestion notifications use a top-level **`state`** of **`COMPLETED`**, **`FAILED`**, or **`ABORTED`**. On success and CKG payloads, check **`additional_info.session_type`** (`AMBIENT`, `FORM_FILLING`, or `CKG_INGESTION`) when one callback URL receives more than one product.

## Event type, trigger, and payload

| Event type | Trigger | How to recognize it |
| :- | :- | :- |
| Ambient session completion | Ambient session finishes processing | `status: SUCCESS` |
| Ambient session failure | Ambient processing fails or the session is aborted | `status: FAILURE` |
| Form filling session completion | Form filling finishes | `status: SUCCESS` |
| Form filling session failure | Form filling fails or the session is aborted | `status: FAILURE` |
| CKG ingestion completed | FHIR push ingestion finishes successfully | `state: COMPLETED` |
| CKG ingestion failed | FHIR push ingestion fails during processing | `state: FAILED` |
| CKG ingestion aborted | FHIR push ingestion stops before it finishes | `state: ABORTED` |

## Delivery, signature, and retries

Suki sends one HTTP <Badge color="blue" size="sm">POST</Badge> to your partner callback URL when a session or CKG job reaches a terminal outcome. Your endpoint must return HTTP **200** within **30 seconds**. If delivery fails, Suki retries up to four more times (**5 attempts** total).

Before you trust the body, verify the **`X-API-Key`** header (HMAC-SHA-256 hex) and the **`generated-at`** timestamp. Return **200** after you accept the notification, then run follow-up work asynchronously when you can.

For setup and verification steps, see [Overview](/documentation/webhook/overview), [Signature verification](/documentation/webhook/signature-verification), and [Configuration](/documentation/webhook/configuration).

## Browse events

<div data-wh-catalog className="suki-use-case-root">
  <section className="suki-use-case-toolbar tut-hub-toolbar" aria-label="Search and filter webhook events">
    <div className="suki-use-case-toolbar-inner release-notes-filter-dropdowns tut-hub-filter-row hub-tools">
      <div className="release-notes-filter-dropdown-field release-notes-filter-search-field">
        <label id="wh-search-label" className="release-notes-filter-row-label" htmlFor="wh-event-search">
          Search
        </label>

        <div className="suki-use-case-search-wrap release-notes-timeline-search-wrap">
          <span aria-hidden="true">
            <WhSearchIcon />
          </span>

          <input id="wh-event-search" type="search" className="suki-use-case-search" data-wh-search="" placeholder="Search status, state, or fields" aria-labelledby="wh-search-label" aria-label="Search webhook events" autoComplete="off" />
        </div>
      </div>

      <div className="release-notes-filter-dropdown-field">
        <label id="wh-product-label" className="release-notes-filter-row-label" htmlFor="wh-product-trigger">
          Browse by Product
        </label>

        <div className="release-notes-filter-dropdown" data-wh-dropdown="product">
          <button type="button" id="wh-product-trigger" className="release-notes-filter-dropdown-trigger" aria-haspopup="listbox" aria-expanded="false" aria-controls="wh-product-listbox" aria-labelledby="wh-product-label">
            <span className="hub-select-pre" aria-hidden="true">Product</span>

            <span className="release-notes-filter-dropdown-value" data-wh-product-value>
              All products
            </span>

            <span className="release-notes-filter-dropdown-chevron" aria-hidden="true">
              <WhFilterChevron />
            </span>
          </button>

          <div id="wh-product-listbox" className="release-notes-filter-dropdown-list" role="listbox" aria-labelledby="wh-product-label" hidden>
            <button type="button" role="option" className="release-notes-product-tab release-notes-product-tab--active" data-wh-product-filter="all" aria-selected="true">
              All products
            </button>

            <button type="button" role="option" className="release-notes-product-tab" data-wh-product-filter="ambient" aria-selected="false">
              Ambient
            </button>

            <button type="button" role="option" className="release-notes-product-tab" data-wh-product-filter="form-filling" aria-selected="false">
              Form Filling
            </button>

            <button type="button" role="option" className="release-notes-product-tab" data-wh-product-filter="ckg" aria-selected="false">
              CKG
            </button>
          </div>
        </div>
      </div>
    </div>

    <p className="tut-hub-filter-note" data-wh-filter-note="" hidden />
  </section>

  <div className="suki-filter-empty" data-wh-empty="" hidden role="status" aria-live="polite">
    <p className="suki-filter-empty-title">No webhook events match.</p>
    <p className="suki-filter-empty-text">Try a different search term, or widen the filters.</p>

    <button type="button" className="suki-filter-empty-clear" data-suki-filter-clear>
      Clear filters
    </button>
  </div>

  <CardGroup cols={3}>
    <div data-wh-card="" data-product="ambient" data-search="ambient success status session_id encounter_id sessions additional_info _links AMBIENT">
      <Card title="Ambient Session Completion" icon="check" href="#ambient-session-completion">
        <Badge size="sm" color="blue">Ambient</Badge>{" "}
        <Badge size="sm" color="green">status: SUCCESS</Badge>

        <br />

        <br />

        Note generation finished. The payload identifies the session and encounter and includes `_links` to retrieve results.
      </Card>
    </div>

    <div data-wh-card="" data-product="ambient" data-search="ambient failure status session_id encounter_id error_code error_detail aborted AMBIENT">
      <Card title="Ambient Session Failure" icon="x" href="#ambient-session-failure">
        <Badge size="sm" color="blue">Ambient</Badge>{" "}
        <Badge size="sm" color="red">status: FAILURE</Badge>

        <br />

        <br />

        Processing failed or the session was aborted. Use `error_code` and `error_detail` to log, alert, or show an error.
      </Card>
    </div>

    <div data-wh-card="" data-product="form-filling" data-search="form filling SUCCESS status session_id encounter_id structured_data FORM_FILLING">
      <Card title="Form Filling Session Completion" icon="check" href="#form-filling-session-completion">
        <Badge size="sm" color="yellow">Form Filling</Badge>{" "}
        <Badge size="sm" color="green">status: SUCCESS</Badge>

        <br />

        <br />

        Form filling finished. Use `_links.structured_data` for form output and `_links.status` for session state.
      </Card>
    </div>

    <div data-wh-card="" data-product="form-filling" data-search="form filling FAILURE status session_id encounter_id error_code error_detail aborted FORM_FILLING">
      <Card title="Form Filling Session Failure" icon="x" href="#form-filling-session-failure">
        <Badge size="sm" color="yellow">Form Filling</Badge>{" "}
        <Badge size="sm" color="red">status: FAILURE</Badge>

        <br />

        <br />

        Form filling failed or was aborted. Use `error_code` and `error_detail` to decide whether to retry, alert, or surface the error.
      </Card>
    </div>

    <div data-wh-card="" data-product="ckg" data-search="ckg fhir COMPLETED state transaction_id organization_id correlation_id CKG_INGESTION">
      <Card title="CKG Ingestion Completed" icon="database" href="#ckg-ingestion-completed">
        <Badge size="sm" color="purple">CKG</Badge>{" "}
        <Badge size="sm" color="green">state: COMPLETED</Badge>

        <br />

        <br />

        FHIR push ingestion finished. CKG notifications use `state`, not `status`, and include `transaction_id` for correlation.
      </Card>
    </div>

    <div data-wh-card="" data-product="ckg" data-search="ckg fhir FAILED state transaction_id error CKG_INGESTION">
      <Card title="CKG Ingestion Failed" icon="database" href="#ckg-ingestion-failed">
        <Badge size="sm" color="purple">CKG</Badge>{" "}
        <Badge size="sm" color="red">state: FAILED</Badge>

        <br />

        <br />

        FHIR push ingestion failed during processing. The payload includes an `error` object with details.
      </Card>
    </div>

    <div data-wh-card="" data-product="ckg" data-search="ckg fhir ABORTED state transaction_id upload expired CKG_INGESTION">
      <Card title="CKG Ingestion Aborted" icon="database" href="#ckg-ingestion-aborted">
        <Badge size="sm" color="purple">CKG</Badge>{" "}
        <Badge size="sm" color="orange">state: ABORTED</Badge>

        <br />

        <br />

        Ingestion stopped before it finished, for example because the upload expired. An `error` object may be present.
      </Card>
    </div>
  </CardGroup>
</div>

## Example payloads

The following examples show the JSON body your callback URL receives. For field definitions and linked API response codes, see [Payload & response](/documentation/webhook/payload-and-response).

<span id="ambient-session-completion" />

### Ambient session completion

<Badge size="sm" color="blue">Ambient</Badge>{" "}
<Badge size="sm" color="green">status: SUCCESS</Badge>

When an Ambient session completes successfully, Suki sends a payload that can look like the following:

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "SUCCESS",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "sessions": [
    "20965414-929a-4f71-a3e5-b92bec07d086",
    "29de56bc-960a-4cd5-b18f-79a798d62874"
  ],
  "additional_info": {
    "session_type": "AMBIENT"
  },
  "_links": {
    "contents": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/content",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "encounter_content": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/content",
        "method": "GET",
        "name": "4d753ce1-bbff-43e1-950a-82dea2d86873",
        "type": "application/json"
      }
    ],
    "structured_data": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/structured-data",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "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"
      }
    ],
    "section_structured_data": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/structured-data/section-structured-data",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "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"
      }
    ],
    "status": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/status",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "transcripts": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/transcript",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ]
  }
}
```

Use the links in `_links` to retrieve note content, structured data, transcripts, or session status.

<span id="ambient-session-failure" />

### Ambient session failure

<Badge size="sm" color="blue">Ambient</Badge>{" "}
<Badge size="sm" color="red">status: FAILURE</Badge>

When an Ambient session fails or is aborted, Suki sends a payload that can look like the following:

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "FAILURE",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "encounter_id": "29de56bc-960a-4cd5-b18f-79a798d62874",
  "error_code": "ERROR_CODE_UNSPECIFIED",
  "error_detail": "Error in transcription"
}
```

<span id="form-filling-session-completion" />

### Form filling session completion

<Badge size="sm" color="yellow">Form Filling</Badge>{" "}
<Badge size="sm" color="green">status: SUCCESS</Badge>

When a Form filling session finishes successfully, Suki sends a payload that can look like the following:

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "SUCCESS",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "sessions": [
    "a953839a-ddcd-407d-b9b0-3ed4b6be4be2"
  ],
  "additional_info": {
    "session_type": "FORM_FILLING",
    "practice_id": "your-practice-id"
  },
  "_links": {
    "encounter_content": [],
    "encounter_structured_data": [],
    "encounter_section_structured_data": [],
    "status": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/status",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "transcripts": [],
    "contents": [],
    "structured_data": [
      {
        "href": "/form-filling/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/structured-data",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "section_structured_data": []
  }
}
```

Use the `structured_data` link to retrieve filled medical form instances. Other `_links` arrays are empty on Form filling webhooks.

<span id="form-filling-session-failure" />

### Form filling session failure

<Badge size="sm" color="yellow">Form Filling</Badge>{" "}
<Badge size="sm" color="red">status: FAILURE</Badge>

When a Form filling session fails, Suki sends a payload that can look like the following:

```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 during form generation"
}
```

<span id="ckg-ingestion-completed" />

### CKG ingestion completed

<Badge size="sm" color="purple">CKG</Badge>{" "}
<Badge size="sm" color="green">state: COMPLETED</Badge>

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"
  }
}
```

<span id="ckg-ingestion-failed" />

### CKG ingestion failed

<Badge size="sm" color="purple">CKG</Badge>{" "}
<Badge size="sm" color="red">state: FAILED</Badge>

When a FHIR push ingestion job fails, 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"
  }
}
```

<span id="ckg-ingestion-aborted" />

### CKG ingestion aborted

<Badge size="sm" color="purple">CKG</Badge>{" "}
<Badge size="sm" color="orange">state: ABORTED</Badge>

When ingestion is aborted, for example because the upload expired, 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"
  }
}
```

<Note>
  Suki does not send separate timeout or cancellation webhooks. If a session fails or is aborted, you get **`status`: `FAILURE`**. If processing finishes, you get **`status`: `SUCCESS`**. For Ambient, that **`SUCCESS`** can still arrive when the recording was silent or too short and session status is **`skipped`**, so confirm status before you treat the visit as note-ready. See [Webhook event types](/documentation/webhook/event-types#session-completion).
</Note>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Payload & response](/documentation/webhook/payload-and-response)** - Field definitions and linked API response codes.

<Icon icon="file-lines" iconType="solid" /> **[Event types](/documentation/webhook/event-types)** - When each notification is sent.

<Icon icon="file-lines" iconType="solid" /> **[Signature verification](/documentation/webhook/signature-verification)** - HMAC verification.

<Icon icon="file-lines" iconType="solid" /> **[Overview](/documentation/webhook/overview)** - Delivery and retry behavior.


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