Webhook Payload & Response

When Suki delivers a webhook notification, it sends a POST request to your callback URL with Content-Type: application/json. Before you process the body, check these request headers so you can confirm the delivery is from Suki:

Header	What it is
`X-API-Key`	Hex-encoded HMAC-SHA-256 signature of this request (see Signature verification).
`generated-at`	Unix time in milliseconds for when Suki built the request. Use it to spot stale or replayed traffic.

How to handle the payload and response

Your handler should verify those headers first, then read the top-level status field in the JSON and branch on "success" or "failure". For the full request specification and sample handler code in Python and TypeScript, refer to the Asynchronous notifications (webhook) API reference.

Payload structure when status is “success” or “failure”

Every webhook body includes a top-level status field. All other fields depend on that value. When status is "success": The payload identifies the session and encounter and provides links to retrieve results. It includes:

session_id, encounter_id (always present)
Optionally: sessions, additional_info, _links

Inside _links, each key is an array of link objects (href, method, name, type). These are the keys you will see in the _links object:

All Link Keys

array

Session-level note content links.

array

Encounter-level content links.

array

Session-level structured clinical data links.

array

Encounter-level structured clinical data links.

array

Status check links.

array

Transcript links.

Use the _links object to get URLs for fetching session content, encounter content, structured clinical data, status, and transcripts from the Ambient APIs. For each link, combine its href with your API base URL and use the correct authentication when you call those follow-up APIs.The sessions array lists the session IDs tied to the encounter so far.

When status is "failure": The payload identifies the session and encounter and describes the error. It includes:

session_id, encounter_id, error_code, error_detail

Use these fields to log the failure, trigger alerts, or show an error in your application. For a summary of completion, failure, timeout, and cancellation events, refer to Event types.

Example payloads

The following examples show the JSON bodies your endpoint receives. Use them to validate your parser and to see how the structure maps to the description above. When status is success: When a session completes and note generation succeeds, your endpoint receives a payload like this:

JSON

{
  "_links": {
    "contents": [
      {
        "href": "/path/to/resource", // the URL to fetch the session content
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "encounter_content": [
      {
        "href": "/path/to/resource", // the URL to fetch the encounter content
        "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", // the URL to fetch the status
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "transcripts": [
      {
        "href": "/path/to/resource", // the URL to fetch the transcripts
        "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"
}

Combine each href in _links with your API base URL and send a GET request with the appropriate authentication to retrieve content, structured data, encounter resources, status, or transcripts. The sessions array lists all session IDs for this encounter. When status is failure: When a session or note generation fails, your endpoint receives a payload like this:

JSON

{
  "encounter_id": "29de56bc-960a-4cd5-b18f-79a798d62874", // the ID of the encounter that failed
  "error_code": "ERROR_CODE_TRANSCRIPTION", // the error code that occurred
  "error_detail": "Error in transcription", // the error detail
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086", // the ID of the session that failed
  "status": "failure"
}

Use error_code and error_detail to log the failure, send an alert, or display an error to the user.

Implementation tips

Return 200 OK quickly and do heavy work (follow-up API calls, database updates) in a background job or queue.
Treat the handler as idempotent; use session_id to detect duplicate deliveries and process each notification only once.
Check generated-at and reject requests that are too old for your risk window, so replayed calls are less useful to an attacker.
Store the secret key in a secrets manager (for example AWS Secrets Manager or Azure Key Vault), not in source control.
Add rate limiting on the public URL so abuse is harder.
Keep the endpoint highly available (for example a load balancer or redundant instances).
Log that a webhook was received plus session_id, encounter_id, and status; avoid logging full bodies if they contain sensitive data.

Responses from Suki webhook endpoint

When you call the Suki Webhook Endpoint (for example, using the href values in _links to fetch content, status, or transcripts), Suki returns an HTTP status and, for errors, a JSON body with code and message.

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

In your application, 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.

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Webhook Payload & Response

How to handle the payload and response

Payload structure when status is “success” or “failure”

Example payloads

Implementation tips

Responses from Suki webhook endpoint

​How to handle the payload and response

​Payload structure when status is “success” or “failure”

​Example payloads

​Implementation tips

​Responses from Suki webhook endpoint

How to handle the payload and response

Payload structure when status is “success” or “failure”

Example payloads

Implementation tips

Responses from Suki webhook endpoint