> ## 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 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 HTTP theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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](/documentation/webhook/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/asynchronous/webhook.mdx) API reference or [Form filling asynchronous notifications](/form-filling-api-reference/asynchronous/webhook.mdx).
## Notification payloads
Every notification includes a top-level field indicating its status or state. The remaining fields depend on its value.
**Payload field tabs (agents):** Ambient, Form filling, and CKG Ingestion each define success/failure (or state) fields and `_links`. Form filling uses `SUCCESS`/`FAILURE`; CKG uses states such as `COMPLETED`/`FAILED`/`ABORTED`. Read all three tabs for the product you handle.
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:
Session-level note content.
Encounter-level note content.
Session-level structured clinical data.
Encounter-level structured clinical data.
Session status resources.
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](/documentation/webhook/event-types).
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:
Session-level medical form output for each Form filling session. Links to `/form-filling/session/{session_id}/structured-data`.
Session status for each session in the encounter. Links to `/session/{session_id}/status`.
Encounter-level structured data aggregated across sessions. Links to `/encounter/{encounter_id}/structured-data`.
Encounter-level note content. Present only when the encounter contains a mix of ambient and Form filling sessions.
Session-level note content (always empty for Form filling sessions).
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.
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.
Identifier returned when the FHIR push job was created. Use this value to correlate the notification with the original upload.
Your partner organization identifier.
Correlation identifier for the request.
Terminal job state. One of `COMPLETED`, `FAILED`, or `ABORTED`.
Time when the ingestion job was created. Omitted if unavailable.
Time when the ingestion job reached its terminal state. Omitted if unavailable.
Present only when `state` is `FAILED` or `ABORTED`.
### Error object
Machine-readable error code.
Human-readable description of the error.
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.
**Example payload tabs (agents):** JSON examples for Ambient, Form filling, and CKG Ingestion success and failure notifications. Use the tab for the webhook type you implement.
### Success payload
When an Ambient session completes successfully, Suki sends a payload that can look like the following:
```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
"_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:
```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
"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.
### 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:
```json theme={"theme":{"light":"github-dark","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": {
"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:
```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
"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:
```json theme={"theme":{"light":"github-dark","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"
}
```
### Success payload
When a FHIR push ingestion job completes successfully, Suki sends a payload that can look like the following:
```json theme={"theme":{"light":"github-dark","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"
}
```
### Failed payload
When a FHIR push ingestion job fails, Suki sends a payload that can look like the following:
```json theme={"theme":{"light":"github-dark","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": "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.
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.
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`.
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](/documentation/webhook/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.
**Linked response tabs (agents):** HTTP status handling when calling `_links` URLs for Ambient, Form filling, and CKG Ingestion. Authenticate Form filling / CKG follow-up calls with your SDP token as described in each tab.
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.
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
```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
"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 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.