Form Filling Webhook Handler

Build a server-side Webhook handler that verifies Form filling notifications, fetches structured data, and saves results to your EHR

This example shows how to build a server-side webhook handler for Form filling results. onSubmit runs in the browser when structured data is ready, but it may not run if the clinician closes the tab before processing finishes.

The example receives a Partner notification webhook after Suki completes backend processing, verifies the request, and fetches structured data to save to your EHR. Webhook session_id maps to ambient_session_id in the SDK. Webhook encounter_id maps to correlation_id when you pass your encounter UUID at session start.

JavaScript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/suki", async (req, res) => {
  // 1. Verify signature (required in production)
  // verifySukiSignature(req.headers, req.body);

  const { status, session_id: sessionId, encounter_id: encounterId } = req.body;

  if (!sessionId) {
    res.status(400).json({ error: "Missing session_id" });
    return;
  }

  if (status === "success") {
    const { structured_data: structured } = await fetchFormFillingStructuredData(sessionId);

    await saveFormsToEhr({
      encounterId,
      sessionId,
      forms: structured.generated_values,
    });
  }

  if (status === "failure") {
    console.error("Form filling session failed", req.body.error_code, req.body.error_detail);
  }

  res.status(200).json({ received: true });
});

async function fetchFormFillingStructuredData(ambientSessionId) {
  const res = await fetch(
    `https://sdp.suki-stage.com/api/v1/form-filling/session/${ambientSessionId}/structured-data`,
    {
      headers: {
        sdp_suki_token: process.env.SUKI_SERVICE_TOKEN,
        sdp_provider_id: process.env.SUKI_PROVIDER_ID,
      },
    }
  );
  if (!res.ok) throw new Error(`structured-data fetch failed: ${res.status}`);
  return res.json();
}

Verify every request with Signature verification. Use session_id as an idempotency key. Refer to Get Form filling structured data for production URLs and auth headers.

Available cookbooks

Available tutorials

Next steps

EHR handoff - Map structured_data to your EHR fields.

Session workflow - Browser vs server delivery.

Webhook quickstart - Endpoint setup and testing.