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

# Form Filling Webhook Overview

> Understand when Suki sends Form filling webhooks, how to interpret session outcomes, and how to retrieve the results

Quick summary

Suki exposes a Form filling webhook to notify your application when a Form filling session reaches a final processing outcome. The top-level `status` is `SUCCESS` or `FAILURE`. A successful notification identifies the session as `FORM_FILLING` in `additional_info.session_type` and provides `_links` to the filled form output and the session status.

Last updated:
November 2026

Form filling webhooks notify your application when Suki finishes processing a Form filling session. Your application can use the notification to check the session status and retrieve the filled forms without repeatedly polling the API.

During partner onboarding, Suki configures a callback URL (An endpoint URL registered by a partner to receive webhook event notifications from Suki, such as session completion or note generation events.) for your account. Suki sends notifications to this URL when a Form filling session completes, is skipped, fails, or is aborted.

The webhook contains the processing outcome, session identifiers, and links to the available results. It does not contain the filled form values. Your application must retrieve that content through the API.

Form filling uses the same callback URL, signature, and delivery rules as every other Suki webhook. What differs is the payload: the `session_id` is your Form filling session ID from [Create Form filling session](https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/create.md), and the links point to the Form filling APIs instead of the Ambient APIs.

## Common use cases

Use the Form filling webhook when you want your application to react as soon as form processing finishes, instead of polling for status.

> [card] Write Filled Forms to the EHR
>
> When the notification reports `SUCCESS`, retrieve the structured data and write the filled form values into your EHR or EMR.

> [card] Open Form Review for the Clinician
>
> Tell the clinician that structured assessment forms are ready for review, or that the session needs attention.

> [card] Run Quality or Analytics Workflows
>
> Use the same notification to start analytics or quality checks on completed forms and update your application state.

> [card] Catch Failures Early
>
> When the notification reports `FAILURE`, log `error_code` and `error_detail`, then decide whether to retry, alert your team, or show an error.

## When Suki sends a Form filling webhook

Suki sends a Form filling webhook after you end a session and processing reaches a final outcome. This includes successful processing, skipped processing, processing failures, and aborted sessions.

Suki does not send a webhook when you create or start a session.

The top-level `status` indicates the outcome reported by the notification:

| Session outcome | Webhook `status` | What your application should do |
| :- | :- | :- |
| Processing completed | `SUCCESS` | Check the session status. Read the structured data to get the filled forms. |
| Processing skipped | `SUCCESS` | Check the session status and the structured data before you show forms to the clinician. |
| Processing failed | `FAILURE` | Record `error_code` and `error_detail`. Decide whether to retry, alert, or show an error. |
| Session aborted | `FAILURE` | Handle the notification as a failed session. |

> [!TIP]
>
> `SUCCESS` means processing reached a successful notification outcome. It does not guarantee that every requested form was filled. Always check the structured data, including `non_generated_values`, before you show results.

## Delivery rules

Your webhook receiver must account for the following behaviors:

* **Cancelled sessions do not generate webhooks.** When you send `CANCEL` while streaming, Suki stops the session without sending a webhook for it.
* **A `FAILURE` notification does not always mean session processing failed.** If `error_code` is `ERROR_CODE_NOTIFICATION_GENERATION_FAILURE`, Suki could not generate the webhook body. The session itself may have completed successfully. Check the session status before reporting a processing error.
* **The same notification can be delivered more than once.** Use `session_id` and `status` to identify and skip notifications your application has already processed.

Use the webhook as a signal to check the session, not as confirmation that every form is ready. Call [Get Form filling session status](https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/status.md) and read the filled forms only after the session has finished.

> [!NOTE]
>
> If you cancelled a session or suspect that you missed a notification, call the same endpoint to check the session's current status.

> [!TIP]
>
> For delivery behavior shared by all Suki webhooks, refer to [Delivery rules](https://developer.suki.ai/documentation/webhook/event-types.md#delivery-rules).

## How a Form filling webhook works

The following sequence shows how Suki delivers a notification and how your application retrieves the results.

**1. End the Form Filling Session**

Your application creates a Form filling session with the form templates you need, streams audio, and ends the session.

**2. Suki Fills the Forms**

Suki generates a filled form instance for each template that it can complete from the conversation.

**3. Suki Sends the Webhook**

Suki sends a POST request to your configured callback URL. The request contains the processing outcome and session identifiers.

**4. Verify the Request and Respond**

Your endpoint verifies the webhook signature and returns HTTP **200** within 30 seconds. Refer to [Signature verification](https://developer.suki.ai/documentation/webhook/signature-verification.md).

**5. Check the Status and Retrieve Results**

When the notification reports `SUCCESS`, call the `status` link if you need to confirm the session finished, then call the `structured_data` link to read the filled forms. Refer to [Retrieve Form filling results](https://developer.suki.ai/documentation/webhook/form-filling/retrieve-results.md).

## What the payload includes

When a Form filling session completes, the webhook contains only two links for each Form filling session in the encounter (One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit.). Form filling creates results for each session, not for the encounter as a whole, so there are no encounter links.

* `structured_data` points to the filled forms.
* `status` points to the session status.

The other link fields, such as `contents`, `transcripts`, and `encounter_content`, are still in the webhook but are empty lists. The webhook never contains the filled form values, so always read them from the `structured_data` link.

A `SUCCESS` webhook also does not mean every form was filled. Any form Suki could not fill is listed in `non_generated_values` when you read the structured data.

## Form filling and ambient sessions in one encounter

The same visit can include an ambient session and a Form filling session. Suki still sends a separate webhook for each one.

* A Form filling webhook covers only Form filling. Its `sessions` list includes Form filling session IDs only.
* An [Ambient webhook](https://developer.suki.ai/documentation/webhook/ambient/overview.md) covers only ambient. Its `sessions` list includes ambient session IDs only.

When the payload reports `SUCCESS`, check `additional_info.session_type`. It is `FORM_FILLING` for this webhook and `AMBIENT` for the Ambient webhook.

## Next steps

 **[Form filling payload reference](https://developer.suki.ai/documentation/webhook/form-filling/payload.md)** - Every field in the success and failure payloads.

 **[Retrieve Form filling results](https://developer.suki.ai/documentation/webhook/form-filling/retrieve-results.md)** - Read filled forms and session status.

 **[Webhook request and response](https://developer.suki.ai/documentation/webhook/payload-and-response.md)** - Headers, the 200 response, and retries.

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