Webhook Payload & Response

Parse Webhook POST request headers, JSON payload fields, _links, and expected callback response formats for session notifications

When Suki sends a Webhook notification, it makes an HTTP POST request to your configured callback URL with the following header:

HTTP

Content-Type: application/json

Request headers

Before processing an HTTP POST request body, verify that the request originated from Suki by validating the following request headers:

Header	Description
X-API-Key	Hex-encoded HMAC-SHA-256 signature for the request. See Signature verification.
generated-at	Unix timestamp, in milliseconds, indicating when Suki generated the request. Use this value to detect stale or replayed requests.

How to handle the request

After verifying the request headers:

1. Parse the JSON request body.
2. Read the top-level status (or state for CKG ingestion) field.
3. Process the notification based on the value of the status field (such as success or failure for Ambient sessions, SUCCESS or FAILURE for Form filling sessions, or COMPLETED, FAILED, or ABORTED for CKG ingestion jobs).
4. On success, use the _links object (if present) to retrieve generated medical form output, note content, and session status.
5. Use session_id or transaction_id as your deduplication key.

For the complete request specification and example implementations in Python and TypeScript, see the Asynchronous notifications (Webhook) API reference or Form filling asynchronous notifications.

Notification payloads

Every notification includes a top-level field indicating its status or state. The remaining fields depend on its value.

Ambient

Every ambient notification includes a top-level status field. The remaining fields depend on its value.

Success payload

When status is success, the payload identifies the completed session and provides links for retrieving generated resources.

Required fields

Field	Description
session_id	Identifier of the completed Ambient session.
encounter_id	Identifier of the encounter associated with the session.

Optional fields

Field	Description
sessions	Array of session IDs associated with the encounter.
additional_info	Additional metadata for the session.
_links	Resource links for retrieving generated content and related resources.

The _links object

The _links object contains one or more collections of resource links. Each link object includes:

Field	Description
href	Relative URL of the resource.
method	HTTP method required to access the resource.
name	Resource name.
type	Response media type.

The following link collections can be included:

Available link collections

contents · array

Session-level note content.

encounter_content · array

Encounter-level note content.

structured_data · array

Session-level structured clinical data.

encounter_structured_data · array

Encounter-level structured clinical data.

status · array

Session status resources.

transcripts · array

Session transcript resources.

To retrieve generated resources, combine each href value with your API base URL and call the corresponding endpoint using the specified HTTP method and appropriate authentication.

If present, the sessions array lists every Ambient session currently associated with the encounter.

Failure payload

When status is failure, the payload identifies the session and describes why processing failed.

Field	Description
session_id	Identifier of the failed session.
encounter_id	Identifier of the associated encounter.
error_code	Machine-readable error code.
error_detail	Human-readable description of the failure.

Use these fields to determine why the request failed and decide whether to retry, alert, or surface the error to users.

For a summary of all ambient notification events, including completion, failure, timeout, and cancellation, see Event types.

Form Filling

Form filling webhooks use the same Notification webhook format as Ambient session webhooks (Partner_WebhookFormat_Notification). They are delivered when the underlying orchestration job type is FORM_FILLING_ORCHESTRATION and the job status is terminal (COMPLETED, SKIPPED, FAILED, or ABORTED).

Form filling sessions differ from Ambient sessions in what resource links they include:

• contents and transcripts are not populated for Form filling sessions.
• encounter_content is omitted when every session in the encounter is a Form filling session. If the encounter contains a mix of ambient and Form filling sessions, encounter_content is included for the encounter as a whole.
• Session-level structured_data links for Form filling sessions point to the Form filling structured data endpoint (/form-filling/session/{session_id}/structured-data), not the ambient structured-data endpoint.

Success payload

When a Form filling session completes successfully, Suki sends a payload that identifies the completed session and provides links for retrieving generated resources.

Required fields

Field	Description
status	Always SUCCESS (or SKIPPED) for successful completions.
session_id	Identifier of the completed Form filling Ambient session.
encounter_id	Identifier of the encounter (session group) associated with the session.

Optional fields

Field	Description
sessions	Sorted list of Ambient session IDs for all external sessions in the encounter, in order of occurrence.
additional_info	Additional metadata for the session. May include practice_id when resolvable from partner organization configuration.
_links	Resource links for retrieving generated form output, encounter-level structured data, and session status.

The _links object

The _links object contains one or more collections of resource links. Each link object includes:

Field	Description
href	Relative URL of the resource. Combine with your API base URL before calling the endpoint.
method	HTTP method required to access the resource (always GET for Form filling links).
name	Resource name (typically the session or encounter ID).
type	Response media type (application/json).

The following link collections are supported for Form filling sessions:

Available link collections

structured_data · array

Session-level medical form output for each Form filling session. Links to /form-filling/session/{session_id}/structured-data.

status · array

Session status for each session in the encounter. Links to /session/{session_id}/status.

encounter_structured_data · array

Encounter-level structured data aggregated across sessions. Links to /encounter/{encounter_id}/structured-data.

encounter_content · array

Encounter-level note content. Present only when the encounter contains a mix of ambient and Form filling sessions.

contents · array

Session-level note content (always empty for Form filling sessions).

transcripts · array

Session transcript resources (always empty for Form filling sessions).

To retrieve generated resources, combine each href value with your API base URL (for example, https://api.example.com/api/v1) and call the corresponding endpoint using the specified HTTP method and appropriate SDP authentication (sdp_suki_token, and sdp_provider_id when required).

Failure payload

When a Form filling session fails or is aborted, the payload identifies the session and describes why processing failed.

Field	Description
status	Always FAILURE.
session_id	Identifier of the failed Form filling session.
encounter_id	Identifier of the associated encounter.
error_code	Machine-readable error code from the job failure output. Known values: ERROR_CODE_UNSPECIFIED, ERROR_CODE_NOTIFICATION_GENERATION_FAILURE.
error_detail	Human-readable description of the failure, when available from the job output.

Use error_code and error_detail to determine why the request failed and decide whether to retry, alert, or surface the error to users.

CKG Ingestion

When a FHIR push ingestion job reaches a terminal state, Suki sends a POST request to your configured callback URL with a JSON payload describing the outcome.

Payload fields

Each CKG ingestion notification contains the following fields.

Available fields

transaction_id · string

Identifier returned when the FHIR push job was created. Use this value to correlate the notification with the original upload.

organization_id · string

Your partner organization identifier.

correlation_id · string

Correlation identifier for the request.

state · string

Terminal job state. One of COMPLETED, FAILED, or ABORTED.

created_at · string (RFC 3339)

Time when the ingestion job was created. Omitted if unavailable.

completed_at · string (RFC 3339)

Time when the ingestion job reached its terminal state. Omitted if unavailable.

error · object

Present only when state is FAILED or ABORTED.

Error object

Error object fields

code · string

Machine-readable error code.

message · string

Human-readable description of the error.

retryable · boolean

Indicates whether retrying the ingestion may succeed.

Example payloads

The following examples show the request body your callback URL receives for successful and failed notifications.

Ambient

Success payload

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

{
  "_links": {
    "contents": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "encounter_content": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "structured_data": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "encounter_structured_data": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "status": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "transcripts": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ]
  },
  "additional_info": {
    "priority": "high"
  },
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "sessions": [
    "20965414-929a-4f71-a3e5-b92bec07d086",
    "29de56bc-960a-4cd5-b18f-79a798d62874"
  ],
  "status": "success"
}

Use the links in the _links object to retrieve generated note content, structured clinical data, transcripts, encounter resources, or session status. Combine each href with your API base URL and authenticate the request before calling the corresponding endpoint.

If present, the sessions array lists every Ambient session currently associated with the encounter.

Failure payload

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

{
  "encounter_id": "29de56bc-960a-4cd5-b18f-79a798d62874",
  "error_code": "ERROR_CODE_TRANSCRIPTION",
  "error_detail": "Error in transcription",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "status": "failure"
}

Use error_code and error_detail to determine why the request failed and decide whether to retry, alert, or surface the error to users.

Form Filling

Success payload (Form filling only encounter)

When a Form filling session completes successfully and the encounter contains only Form filling sessions, Suki sends a payload that can look like the following:

{
  "status": "SUCCESS",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "sessions": [
    "a953839a-ddcd-407d-b9b0-3ed4b6be4be2"
  ],
  "additional_info": {
    "practice_id": "your-practice-id"
  },
  "_links": {
    "encounter_content": [],
    "encounter_structured_data": [
      {
        "href": "/encounter/4d753ce1-bbff-43e1-950a-82dea2d86873/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": [],
    "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"
      }
    ]
  }
}

Use the structured_data link to retrieve filled medical form instances. Use the status link to confirm the session reached completed. Use encounter_structured_data when you need aggregated structured output across all sessions in the encounter.

Success payload (Mixed Ambient and Form filling encounter)

When an encounter contains both ambient and Form filling sessions, each session type receives appropriate links. Form filling sessions omit content and transcript links, while Ambient sessions include them:

{
  "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": {},
  "_links": {
    "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"
      }
    ],
    "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"
      }
    ],
    "transcripts": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/transcript",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "type": "application/json"
      }
    ],
    "contents": [
      {
        "href": "/session/20965414-929a-4f71-a3e5-b92bec07d086/content",
        "method": "GET",
        "name": "20965414-929a-4f71-a3e5-b92bec07d086",
        "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": "/form-filling/session/29de56bc-960a-4cd5-b18f-79a798d62874/structured-data",
        "method": "GET",
        "name": "29de56bc-960a-4cd5-b18f-79a798d62874",
        "type": "application/json"
      }
    ]
  }
}

Failure payload

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

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

CKG Ingestion

Success payload

When a FHIR push ingestion job completes successfully, Suki sends a payload that can look like the following:

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

Failed payload

When a FHIR push ingestion job fails, Suki sends a payload that can look like the following:

{
  "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": "INGESTION_ERROR",
    "message": "Human-readable description of what went wrong",
    "retryable": true
  }
}

Common use cases

Use Webhook notifications to detect when a session or ingestion job completes or fails and trigger automated workflows.

Ambient Sessions

Use Ambient session completion or failure notifications to automate downstream workflows:

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

Form Filling Sessions

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.

CKG Ingestion

Use CKG ingestion notifications to detect when a FHIR push ingestion job has completed or failed and trigger automated workflows:

• Update patient records in your EHR or EMR.
• Notify clinicians or care teams that new patient data is available.
• Trigger downstream analytics or reporting workflows.
• Update application state after a successful ingestion.
• Retry failed ingestion jobs when appropriate.

Implementation recommendations

Follow these practices when implementing your callback URL to receive notifications for Ambient session, Form filling, and CKG data ingestion events:

1. Verify the request signature before processing the payload. See Signature verification.
2. Validate the generated-at timestamp to reject stale requests.
3. Process notifications asynchronously and return a 2xx response as quickly as possible.
4. Treat notifications as idempotent by using session_id or transaction_id as the deduplication key.
5. Store your webhook secret securely in a secrets manager.
6. Log request metadata instead of full payloads whenever possible.
7. Protect the endpoint with rate limiting and high availability.
8. Fetch structured output from the _links.structured_data endpoint rather than expecting inline form data in the webhook body.
9. Handle non_generated_values in the structured data response to identify templates that were requested but not filled.

Responses from linked API endpoints

After receiving a success Webhook, call the linked endpoints to retrieve generated output.

Ambient

When you call one of the resource URLs returned in the _links object, the Ambient APIs return standard HTTP status codes.

Code	Description
200	OK. The request succeeded.
400	Bad Request. The request was invalid. Example: {"code": 400, "message": "invalid request"}
401	Unauthorized. The token is invalid or authentication failed. Example: {"code": 401, "message": "invalid token"}
500	Internal Server Error. The server encountered an error. Example: {"code": 500, "message": "internal server error"}

Handle 401 by re-authenticating or refreshing the token. Handle 400 by fixing the request or showing an error. Consider retrying on 5xx when appropriate.

Form Filling

After receiving a success webhook, call the linked endpoints to retrieve generated output. Authenticate each request with your SDP token.

GET structured data

Endpoint: GET /api/v1/form-filling/session/{ambient_session_id}/structured-data

Returns generated and non-generated medical form instances for the session.

Response body

Field	Description
structured_data.generated_values	Array of filled medical form instances produced for this session. Each entry is a full MedicalFormInstance with id, form_template_id, data, status, and related fields.
structured_data.non_generated_values	Array of form templates that were requested but did not produce a filled instance. Each entry contains at minimum form_template_id.

Example response

{
  "structured_data": {
    "generated_values": [
      {
        "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0",
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template",
        "correlation_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "patient_id": "patient-123",
        "status": "MEDICAL_FORM_STATUS_COMPLETED",
        "title": "Adult Vitals",
        "created_at": "2026-01-01T00:00:00Z",
        "data": {},
        "metadata": {}
      }
    ],
    "non_generated_values": [
      {
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
      }
    ]
  }
}

GET session status

Endpoint: GET /api/v1/form-filling/session/{ambient_session_id}/status

Returns the current lifecycle state of the Form filling session.

Status	Description
created	Session has been created but not yet started.
ready	Session has been started.
running	Session is generating form content.
paused	Session is paused.
aborted	Session was aborted by the client.
failed	Session failed due to an error.
completed	Session completed successfully.

HTTP status codes

When you call Form filling API endpoints, Suki returns standard HTTP status codes:

Code	Description
200	OK. The request succeeded.
400	Bad Request. The request was invalid. Example: {"code": 400, "message": "invalid request"}
401	Unauthorized. The token is invalid or authentication failed. Example: {"code": 401, "message": "invalid token"}
404	Not Found. The requested resource does not exist. Example: {"code": 404, "message": "not found"}
500	Internal Server Error. Example: {"code": 500, "message": "internal server error"}

Handle 401 by re-authenticating or refreshing the token. Handle 400 by fixing the request or showing an error. Consider retrying on 5xx when appropriate.

CKG Ingestion

CKG data ingestion notifications do not return any resource retrieval links (_links) as the operation is an asynchronous ingestion process. All status, transaction details, and error messages are provided directly within the notification payload.