> ## 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 the steps to receive Webhook notifications from Suki when an Ambient session completes or fails.
During partner onboarding, you provide Suki with a callback URL. Whenever a supported event occurs, Suki sends an HTTP POST request to that endpoint. Your application verifies the request, processes the payload, and returns a successful response.
## Prerequisites
Before you begin, make sure you have:
* Completed [Partner onboarding](/documentation/get-started/partner-onboarding).
* Provided Suki with an HTTPS callback URL. See [Configuration](/documentation/webhook/configuration).
* Received your partner secret key. You use this to verify incoming Webhook requests. See [Signature verification](/documentation/webhook/signature-verification).
* A publicly accessible HTTPS endpoint (TLS 1.2 or later).
* An integration that creates and ends Ambient sessions using the Ambient APIs or a Suki SDK.
Suki configures **one Webhook callback URL** per partner during onboarding. You cannot create or update the callback URL through an API or self-service portal.
## Implementation
Provide Suki with the HTTPS endpoint that should receive Webhook notifications, for example:
`https://your-app.example.com/webhooks/notification`
Suki stores this URL for your partner account and sends all Webhook notifications to this endpoint.
Implement an endpoint that accepts:
* POST requests.
* Content-Type: application/json.
Read the raw request body before parsing JSON. You'll use the raw payload when verifying the Webhook signature.
Before processing the payload:
* Read the generated-at and X-API-Key headers.
* Verify the HMAC-SHA-256 signature using your partner secret.
* Reject the request if signature verification fails.
For complete verification steps and examples, see [Signature verification](/documentation/webhook/signature-verification).
After verification succeeds:
* Parse the JSON payload.
* Read the top-level status field.
* Handle the event based on its value.
**Success**:
Use the returned session\_id, encounter\_id, and \_links to retrieve notes, transcripts, or status from the Ambient APIs.
**Failure**:
Use error\_code and error\_detail to log the failure, notify your application, or display an appropriate message.
See [Webhook payload & response](/documentation/webhook/payload-and-response) for the complete payload schema.
Return an HTTP 2xx response after successfully receiving the Webhook.
You can process additional work asynchronously after sending the response.
Run a complete ambient workflow:
* Create an Ambient session.
* Stream audio.
* End the session.
* Wait for processing to complete.
Verify that your endpoint:
* Receives the Webhook.
* Verifies the signature.
* Processes the payload.
* Returns a successful response.
If you need a sample workflow, see the [Ambient API quickstart](/api-reference/quickstart).
## Example Webhook handlers
The following examples show a basic Webhook endpoint that receives notifications and processes successful and failed events.
**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.
```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/webhooks/notification", methods=["POST"])
def Webhook():
# Verify signature before parsing the payload.
payload = request.get_json()
if payload["status"] == "success":
print(payload["session_id"])
print(payload["encounter_id"])
elif payload["status"] == "failure":
print(payload["error_code"])
print(payload["error_detail"])
return jsonify({"status": "ok"}), 200
```
```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhooks/notification", (req, res) => {
// Verify signature before processing.
const payload = req.body;
if (payload.status === "success") {
console.log(payload.session_id);
console.log(payload.encounter_id);
}
if (payload.status === "failure") {
console.log(payload.error_code);
console.log(payload.error_detail);
}
res.status(200).json({ status: "ok" });
});
```
## Available cookbooks
## Next steps
* Learn more about event types in the [Webhook event types](/documentation/webhook/event-types) guide.
* Implement a secure connection with [Signature verification](/documentation/webhook/signature-verification) process.
* Review the [Webhook payload & response](/documentation/webhook/payload-and-response) schema for the complete payload schema.
* Refer to the [Webhook API reference](/api-reference/asynchronous/webhook.mdx) for the OpenAPI specification and additional examples.