Skip to main content
This guide walks you through how to receive Suki notification webhooks in your application. You configure a callback URL during onboarding, implement a secure POST handler on your server, and process session completion or failure events when Suki calls your endpoint.

​
Prerequisites

Before you start, make sure you have:
  • Completed Partner onboarding
  • Provided Suki with your callback URL (HTTPS) and received confirmation that it is configured on your partner record. See Configuration.
  • Your partner secret key from Suki. You use it on your server to verify each incoming POST. See Signature verification.
  • A server-side endpoint reachable from the internet over HTTPS (TLS 1.2 or higher)
  • An integration path that creates and ends Ambient sessions (direct API, Web SDK, Mobile SDK, or Headless Web SDK). Webhooks fire when those sessions complete or fail.
You cannot register or change your webhook URL through a self-service portal or API. Suki configures one callback URL per partner during onboarding.

​
Steps

Confirm your callback URL with Suki

Share the full HTTPS URL of the endpoint that will receive notifications (for example https://your-app.example.com/webhooks/notification) with the Suki team during partner onboarding. Suki stores it at the partner level and uses it for all webhook deliveries for your organization.

Implement a POST handler on your server

Host an endpoint that accepts POST requests with Content-Type: application/json. Configure your framework to read the raw request body before JSON parsing. Suki calls this URL when a session completes, fails, times out, or is cancelled.

Verify the signature on every request

Read the generated-at and X-API-Key headers and verify the HMAC-SHA-256 signature with your partner secret key before you parse the body. If verification fails, return 4xx and stop. Refer to Signature verification for the exact steps and code examples.

Parse the JSON and branch on status

After verification succeeds, parse the body and read the top-level status field. Branch on "success" or "failure". For field-level detail and example JSON, refer to Payload & Response.

Process the notification

  • Success: Use session_id, encounter_id, and _links to fetch note content, transcripts, or status from the Ambient APIs. Combine each href with your API base URL and use the correct authentication when you call those follow-up APIs.
  • Failure: Log error_code and error_detail, alert your application, or surface an error to the user.

Return 2xx to acknowledge receipt

Respond with 200 (or another 2xx) after you accept the notification so Suki can consider it delivered. You can run follow-up API calls or queue work after the response if needed.

Test end to end

Run an Ambient session through your integration (create session, stream audio, end session). When processing finishes, Suki sends a POST to your callback URL. Confirm your handler verifies the signature, parses the payload, and processes the event. Refer to the Ambient API quickstart if you need a session workflow to test against.

​
Next steps

Refer to Payload & Response for payload structure, example JSON bodies, implementation tips, and follow-up API response codes. Refer to Event types for session completion, failure, timeout, and cancellation events. Refer to Signature verification for HMAC-SHA-256 verification steps and Python and TypeScript examples. Refer to the Asynchronous notifications (webhook) API reference for the OpenAPI specification and sample handler code.
Last modified on June 12, 2026