Skip to main content
Suki sends each notification as a POST with Content-Type: application/json. Every delivery includes headers you use to verify the request before you trust the body:
HeaderWhat it is
X-API-KeyHex-encoded HMAC-SHA-256 signature of this request (see Signature verification).
generated-atUnix time in milliseconds for when Suki built the request. Use it to spot stale or replayed traffic.
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

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). Following are the keys you will see in the _links object:
  • contents: Session-level note content.
  • encounter_content: Encounter-level content.
  • structured_data: Session-level structured clinical data.
  • encounter_structured_data: Encounter-level structured clinical data.
  • status: Status checks.
  • transcripts: Transcripts.
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. 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. 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.
CodeDescription
200OK. The request succeeded.
400Bad Request. The request was invalid. Example: {"code": 400, "message": "invalid request"}
401Unauthorized. The token is invalid or authentication failed. Example: {"code": 401, "message": "invalid token"}
500Internal 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.
Last modified on June 12, 2026