Skip to main content
Quick summary
Suki Webhooks let your application receive real-time HTTP notifications when an Ambient, Form filling, session completes or fails or when an asynchronous FHIR push ingestion (CKG) job finishes. You can use these events to automate workflows such as updating patient records, creating Patient summaries, notifying care teams, or triggering downstream processing of clinical documentation.

To receive notifications, provide a Webhook callback URL. When one of these events occurs, Suki sends a POST request to your endpoint with the event payload. You can choose between both push and pull notification models, allowing you to choose the integration pattern that best fits your application.
Last updated:August 2026
Notification Webhooks are available through the Partner APIs. Sessions created with the Web SDK, Mobile SDK, or Headless Web SDK or Form filling APIs use the same platform Webhook callbacks.

API Reference

To view and implement your Webhook endpoint, refer to the following API reference:
Asynchronous Notifications API
Suki provides Webhook APIs that enable your application to receive real-time HTTP push notifications whenever Ambient, Form filling sessions complete or fail or when an asynchronous FHIR push ingestion (CKG) job finishes. This allows you to build integrations that automatically respond to these critical events, such as updating patient records, creating Patient summaries, notifying care teams, or triggering downstream processing of clinical documentation. For a comprehensive understanding of the object types and data structures included in Webhook payloads, refer to the Payload & response guide. Suki Webhooks are configured per partner, allowing you to specify a callback URL for event delivery. You host this URL, and Suki sends a POST request to it upon relevant session events. While Suki supports both push (Webhooks) and pull-based mechanisms, this guide focuses on push-based notifications and how this capability integrates across our various APIs and SDKs.
Only authorized partner accounts or applications with appropriate permissions can configure and call Suki Webhook APIs, ensuring secure and controlled access to your integration settings and events.

​
How Webhooks work in Suki

A Suki Webhook is an HTTP POST request sent to a URL you specify. This push notification is automatically triggered by Suki when an Ambient, Form filling session completes, fails, times out, or is cancelled. Your Webhook endpoint must meet the following conditions:
  • It must be a publicly accessible HTTPS URL (non-localhost).
  • It must respond to the Suki Webhook POST request with an HTTP 200 (“OK”) status code within 30 seconds.
If a delivery fails (e.g., server unavailable, response time exceeds 30 seconds, or a non-200 HTTP status code is returned), Suki will retry the push a maximum of four times, resulting in a total of 5 attempts. To ensure the authenticity of a Webhook POST request, you should follow the steps outlined in Signature verification guide. This helps confirm that the request originates from Suki.

​
Push vs pull

Suki can deliver notifications in two main ways:
  • Pull: Your application repeatedly asks Suki whether something has changed (for example, Polling the Session Status endpoint). Your system is responsible for when and how often to check.
  • Push: Suki sends a request to your application when an event happens. Your application exposes an endpoint that Suki calls; you do not need to poll.
Suki supports both push and pull based on partner requirements. When you choose to use the push mechanism, Suki sends a single POST request to a callback URL that you provide when a session completes, fails, times out, or is cancelled.
With the push mechanism, you host the callback URL and the infrastructure that receives the notification.Suki does not store or queue notifications; delivery is one-way and immediate.

​
Notification capability across all offerings

Webhook notifications are part of the Suki Developer Platform APIs. You register a Webhook callback URL at the partner level during onboarding; that URL is used for all sessions created under your partner account.
The Web SDK, Mobile SDK, and Headless Web SDK all use the same partner Webhook. Sessions created through those SDKs still trigger callbacks to your URL.
When a session is started and ended from any of these clients, the same platform backend processes it and sends the Webhook notification to your callback URL.
We configure one Webhook URL per partner. That single URL receives all Webhook notifications for your organization, whether the session was created with the direct API, Web SDK, Mobile SDK, or Headless Web SDK. You do not need a separate URL for each client to receive notifications.

​
CKG data ingestion notifications

In addition to Ambient session notifications, Suki sends Webhook notifications when an asynchronous FHIR push ingestion (CKG) job finishes. After your application uploads FHIR (Fast Healthcare Interoperability Resources) data to Suki, the ingestion process runs asynchronously. When the job reaches a terminal state, Suki sends a single POST request to your configured Webhook callback URL with the final result. When you configure a Webhook callback URL for CKG ingestion notifications, you use the same infrastructure as Ambient session notifications:
  • Use the same callback URL.
  • Suki delivers the notification using the same delivery and retry behavior.
  • Verify the request signature using the same request signing mechanism as Ambient session notifications.
Before processing the payload, verify the request signature using the X-API-Key and generated-at headers as described in Signature verification guide.
The CKG ingestion Webhook has its own payload format. It does not use the ambient Webhook status: "success" | "failure" payload structure, regardless of your configured ambient WebhookFormat.

​
Common use cases

Use Suki Webhooks to automate workflows for ambient sessions and CKG data ingestion without polling Suki APIs.

Ambient

Ambient session automation

When an ambient session completes, fails, times out, or is canceled, you can:
  • Synchronize completed clinical notes with your EHR or EMR.
  • Trigger downstream workflows such as coding, billing, or document processing.
  • Notify clinicians or care teams when a session completes or requires attention.
  • Start custom workflows based on the session status.

CKG data ingestion

When an asynchronous FHIR (Fast Healthcare Interoperability Resources) data ingestion job reaches a terminal state, Suki sends a webhook indicating whether the ingestion succeeded or failed. You can use this event to:
  • Generate Patient Summaries after the uploaded data is available in the Clinical Knowledge Graph (CKG).
  • Synchronize newly ingested patient data with your EHR, EMR, or other clinical systems.
  • Notify clinicians that updated patient data is available.
  • Trigger downstream analytics, reporting, or other data processing workflows.
  • Retry or investigate failed ingestion jobs.

CKG

Form Filling

Form Filling Session Automation

Use Form filling webhook notifications to detect when a medical form session has completed or failed and trigger automated workflows:
  • Update EHR or EMR records with generated form data.
  • Notify clinicians that structured assessment forms are ready for review.
  • Trigger downstream analytics or quality workflows on completed forms.
  • Update application state after a successful Form filling session.
  • Surface or retry failed form generation based on error_code and error_detail.

Quickstart

Step-by-step setup: prerequisites, implement your endpoint, verify, and test.

Payload & Response

Payload structure, example JSON, implementation tips, and follow-up API responses.

Signature Verification

Verify HMAC-SHA-256 signatures with your partner secret key before you trust the body.

Configuration

Register your callback URL during onboarding and meet endpoint requirements.

Event Types

Session completion, failure, timeout, and cancellation events your endpoint receives.
Last modified on August 7, 2026