> ## 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 Quickstart

> Step-by-step guide to configure, implement, and test a Suki notification webhook endpoint

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](/documentation/partner-onboarding)
* Provided Suki with your **callback URL** (HTTPS) and received confirmation that it is configured on your partner record. See [Configuration](/documentation/webhook/configuration).
* Your partner **secret key** from Suki. You use it on your server to verify each incoming POST. See [Signature verification](/documentation/webhook/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.

<Note>
  You cannot register or change your webhook URL through a self-service portal or API. Suki configures one callback URL per partner during onboarding.
</Note>

## Steps

<Steps>
  <Step title="Confirm your callback URL with Suki" icon="gear">
    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](/documentation/partner-onboarding). Suki stores it at the partner level and uses it for all webhook deliveries for your organization.
  </Step>

  <Step title="Implement a POST handler on your server" icon="code">
    Host an endpoint that accepts <Badge color="blue" size="sm">POST</Badge> 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.
  </Step>

  <Step title="Verify the signature on every request" icon="lock">
    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](/documentation/webhook/signature-verification) for the exact steps and code examples.
  </Step>

  <Step title="Parse the JSON and branch on status" icon="file-lines">
    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](/documentation/webhook/payload-and-response).
  </Step>

  <Step title="Process the notification" icon="bell">
    * **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.
  </Step>

  <Step title="Return 2xx to acknowledge receipt" icon="check">
    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.
  </Step>

  <Step title="Test end to end" icon="play">
    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](/api-reference/quickstart) if you need a session workflow to test against.
  </Step>
</Steps>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Payload & Response](/documentation/webhook/payload-and-response) for payload structure, example JSON bodies, implementation tips, and follow-up API response codes.

<Icon icon="file-lines" iconType="solid" /> Refer to [Event types](/documentation/webhook/event-types) for session completion, failure, timeout, and cancellation events.

<Icon icon="file-lines" iconType="solid" /> Refer to [Signature verification](/documentation/webhook/signature-verification) for HMAC-SHA-256 verification steps and Python and TypeScript examples.

<Icon icon="file-lines" iconType="solid" /> Refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference for the OpenAPI specification and sample handler code.