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.
• Provided Suki with an HTTPS callback URL. See Configuration.
• Received your partner secret key. You use this to verify incoming Webhook requests. See 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

1. Configure Webhook Callback URL

   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.

2. Create Webhook 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.

3. Verify Webhook Request

   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.

4. Process Webhook Event

   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 for the complete payload schema.

5. Return Successful Response

   Return an HTTP 2xx response after successfully receiving the Webhook.

   You can process additional work asynchronously after sending the response.

6. Test Webhook Integration

   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.

Example Webhook handlers

The following examples show a basic Webhook endpoint that receives notifications and processes successful and failed events.

Python

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

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

WebhooksAPI

Verify Webhook HMAC Signature

Verify HMAC before parsing JSON.

5 min

Available tutorials

Webhooks

Build a Webhook Notification Receiver

Verify HMAC signatures, parse partner notifications, and handle success and failure events.

10 minBeginner

Next steps

• Learn more about event types in the Webhook event types guide.
• Implement a secure connection with Signature verification process.
• Review the Webhook payload & response schema for the complete payload schema.
• Refer to the Webhook API reference for the OpenAPI specification and additional examples.