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

> Register your webhook callback URL during partner onboarding and meet endpoint requirements for receiving Suki notifications

Webhook configuration is done during [Partner onboarding](/documentation/get-started/partner-onboarding). You provide Suki with the **callback URL** (the full URL of the endpoint that will receive <Badge color="blue" size="sm">POST</Badge> requests). This URL is stored at the partner level and is used for all webhook notifications for your organization.

Suki also gives you a **secret key** on your partner record. You use that key only on your server to prove each incoming <Badge color="blue" size="sm">POST</Badge> really came from Suki (see [Signature verification](/documentation/webhook/signature-verification)). Treat it like a password.

## How webhook delivery works

<img src="https://mintcdn.com/suki-1e08f176/JWCBr7FDuYx75ifb/documentation/assets/webhook-configuration-light.svg?fit=max&auto=format&n=JWCBr7FDuYx75ifb&q=85&s=fe186a4828ad72ff4ead3dc382aeec82" alt="Diagram: provide callback URL during partner onboarding, Suki stores it on the partner record, and sends HTTPS POST notifications when sessions complete or fail" className="block dark:hidden w-full max-w-4xl mx-auto my-6" width={800} height={260} loading="eager" decoding="async" data-path="documentation/assets/webhook-configuration-light.svg" />

<img src="https://mintcdn.com/suki-1e08f176/JWCBr7FDuYx75ifb/documentation/assets/webhook-configuration-dark.svg?fit=max&auto=format&n=JWCBr7FDuYx75ifb&q=85&s=3ee49cebd83801e63121080f0c5a1402" alt="Diagram: provide callback URL during partner onboarding, Suki stores it on the partner record, and sends HTTPS POST notifications when sessions complete or fail" className="hidden dark:block w-full max-w-4xl mx-auto my-6" width={800} height={260} loading="eager" decoding="async" data-path="documentation/assets/webhook-configuration-dark.svg" />

During onboarding you share your **callback URL** with Suki. Suki stores it on your **partner record** along with your **secret key**. When an ambient session completes or fails, Suki sends a single <Badge color="blue" size="sm">POST</Badge> to that URL. Your server verifies the signature, processes the payload, and returns **2xx**.

<Note>
  You cannot register or change your webhook URL through a self-service portal or API. Provide your callback URL to the Suki team (for example, during [partner onboarding](/documentation/get-started/partner-onboarding)). Suki will configure it for your partner account and confirm the URL with you once it is set.
</Note>

Your endpoint must follow these requirements:

* Accept <Badge color="blue" size="sm">POST</Badge> requests over **HTTPS** only, with **TLS 1.2** or higher. Suki will not send webhooks to **HTTP** URLs.
* Be reachable from the internet (no localhost or private IPs in production).
* Respond with **2xx** (for example, 200) on successful receipt so Suki can consider the notification delivered. Handle validation and business logic after returning 200 if needed.

## Security best practices

<AccordionGroup>
  <Accordion icon="lock" title="Use HTTPS Only">
    Your callback URL must use **HTTPS** with **TLS 1.2** or higher. Never use plain HTTP for webhooks.
  </Accordion>
</AccordionGroup>

## Next steps

<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 [Security & best practices](/api-reference/security-best-practices#webhook-security) for platform-wide guidance.