Form Filling Asynchronous Notifications

Webhook endpoint for receiving asynchronous notifications when Form filling session processing completes

POST /webhooks/notification

Receive asynchronous notifications (partner webhook)

cURL

curl --request POST \
  --url https://sdp.suki.ai/webhooks/notification \
  --header 'Content-Type: application/json' \
  --data '
{
  "encounter_id": "29de56bc-960a-4cd5-b18f-79a798d62874",
  "error_code": "ERROR_CODE_TRANSCRIPTION",
  "error_detail": "Error in transcription",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "status": "FAILURE"
}
'

200

This response has no body data.

Use this endpoint to implement an HTTP endpoint in your application that receives Webhook requests from Suki. This endpoint should be hosted by your application to receive notifications about Form filling session completion or failure.

Host this endpoint on your server. Suki sends a POST when Form filling processing completes or fails. The payload session_id is the Form filling session ID from Create Form filling session.

Learn more about how webhooks work and how to implement your webhook endpoint in Notification webhook for partners.

Code examples

Python

import hashlib
import hmac
import json

from flask import Flask, jsonify, request

app = Flask(__name__)
secret_key = "<partner_secret_key>"


@app.route("/webhooks/notification", methods=["POST"])
def handle_webhook():
    raw_body = request.get_data(as_text=True)
    timestamp = request.headers.get("generated-at", "")
    expected_signature_hex = request.headers.get("X-API-Key", "")
    computed_signature_hex = hmac.new(
        secret_key.encode("utf-8"),
        f"{timestamp}:{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    if not expected_signature_hex or not hmac.compare_digest(
        computed_signature_hex, expected_signature_hex
    ):
        return jsonify({"error": "Invalid signature"}), 401

    try:
        data = json.loads(raw_body)
    except json.JSONDecodeError:
        return jsonify({"error": "Invalid request"}), 400

    status = data.get("status")

    if status == "SUCCESS":
        session_id = data.get("session_id")
        encounter_id = data.get("encounter_id")
        print(f"Form filling session {session_id} completed (encounter {encounter_id})")

        links = data.get("_links") or {}
        for link in links.get("structured_data") or []:
            print(f"  Structured data: {link.get('method')} {link.get('href')}")
        for link in links.get("status") or []:
            print(f"  Status: {link.get('method')} {link.get('href')}")

        return jsonify({"message": "Notification received"}), 200

    if status == "FAILURE":
        print(
            f"Form filling session {data.get('session_id')} failed "
            f"(encounter {data.get('encounter_id')}): "
            f"{data.get('error_code')} - {data.get('error_detail')}"
        )
        return jsonify({"message": "Failure notification received"}), 200

    return jsonify({"error": "Unknown status"}), 400


if __name__ == "__main__":
    app.run(port=3000)

TypeScript

import crypto from "crypto";
import express from "express";

const app = express();
const secretKey = "<partner_secret_key>";

app.post("/webhooks/notification", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = Buffer.isBuffer(req.body) ? req.body.toString("utf8") : String(req.body ?? "");
  const timestamp = String(req.headers["generated-at"] ?? "");
  const expectedSignatureHex = String(req.headers["x-api-key"] ?? "");
  const computedSignatureHex = crypto
    .createHmac("sha256", secretKey)
    .update(`${timestamp}:${rawBody}`, "utf8")
    .digest("hex");

  const signaturesMatch =
    Boolean(expectedSignatureHex) &&
    computedSignatureHex.length === expectedSignatureHex.length &&
    crypto.timingSafeEqual(
      Buffer.from(computedSignatureHex, "utf8"),
      Buffer.from(expectedSignatureHex, "utf8"),
    );

  if (!signaturesMatch) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  let data: Record<string, any>;
  try {
    data = JSON.parse(rawBody);
  } catch {
    return res.status(400).json({ error: "Invalid request" });
  }

  if (data.status === "SUCCESS") {
    console.log(
      `Form filling session ${data.session_id} completed (encounter ${data.encounter_id})`,
    );

    const links = data._links ?? {};
    (links.structured_data ?? []).forEach((link: { method?: string; href?: string }) => {
      console.log(`  Structured data: ${link.method} ${link.href}`);
    });
    (links.status ?? []).forEach((link: { method?: string; href?: string }) => {
      console.log(`  Status: ${link.method} ${link.href}`);
    });

    return res.status(200).json({ message: "Notification received" });
  }

  if (data.status === "FAILURE") {
    console.log(
      `Form filling session ${data.session_id} failed (encounter ${data.encounter_id}): ` +
        `${data.error_code} - ${data.error_detail}`,
    );
    return res.status(200).json({ message: "Failure notification received" });
  }

  return res.status(400).json({ error: "Unknown status" });
});

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

Body

application/json

Webhook payload Suki sends when session processing fails.

encounter_id · string

Id of the encounter to which the payload belongs.

Example:

"29de56bc-960a-4cd5-b18f-79a798d62874"

error_code · string

Error code.

Example:

"ERROR_CODE_TRANSCRIPTION"

error_detail · string

Details of the error, if any.

Example:

"Error in transcription"

session_id · string

Id of the session that failed.

Example:

"20965414-929a-4f71-a3e5-b92bec07d086"

status · string

Example:

"FAILURE"

Response

200

OK