Skip to main content
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 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, 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.

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.

Open Form Review for the Clinician

Tell the clinician that structured assessment forms are ready for review, or that the session needs attention.

Run Quality or Analytics Workflows

Use the same notification to start analytics or quality checks on completed forms and update your application state.

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:
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 and read the filled forms only after the session has finished.
If you cancelled a session or suspect that you missed a notification, call the same endpoint to check the session’s current status.
For delivery behavior shared by all Suki webhooks, refer to Delivery rules.

​
How a Form filling webhook works

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

End the Form Filling Session

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

Suki Fills the Forms

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

Suki Sends the Webhook

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

Verify the Request and Respond

Your endpoint verifies the webhook signature and returns HTTP 200 within 30 seconds. Refer to Signature verification.

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.

​
What the payload includes

When a Form filling session completes, the webhook contains only two links for each Form filling session in the . 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 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 - Every field in the success and failure payloads. Retrieve Form filling results - Read filled forms and session status. Webhook request and response - Headers, the 200 response, and retries. Form filling asynchronous notifications - OpenAPI specification and sample handlers.
Last modified on November 5, 2026