Build Webhook Notification Receiver

// Webhook notification tutorial (TypeScript / Express)
// Flow: read raw body → verify HMAC-SHA-256 → parse JSON → branch on status → return 2xx
// Install: npm install express
// Prefer Node crypto for HMAC. Keep the partner secret key on your backend only.

import crypto from 'crypto';
import express from 'express';

const app = express();

// ---------------------------------------------------------------------------
// Replace with your partner secret key from onboarding (server-side only)
// ---------------------------------------------------------------------------
const SECRET_KEY = '<partner_secret_key>'; // Example only — replace with your partner webhook secret from onboarding

// express.raw keeps the exact body bytes needed for HMAC verification.
app.post(
  '/webhooks/notification',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    // 1) Read the raw body exactly as Suki sent it (before JSON parsing).
    const rawBody = Buffer.isBuffer(req.body)
      ? req.body.toString('utf8')
      : String(req.body ?? '');
    const timestamp = String(req.headers['generated-at'] ?? '');
    const message = `${timestamp}:${rawBody}`;

    // 2) Recompute HMAC-SHA-256 and compare to X-API-Key (constant-time).
    const expectedSignatureHex = String(req.headers['x-api-key'] ?? '');
    const computedSignatureHex = crypto
      .createHmac('sha256', SECRET_KEY)
      .update(message, 'utf8')
      .digest('hex');

    // Reject missing signatures before compare (empty header must not verify).
    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' });
    }

    // 3) Signature matched. Safe to parse JSON and branch on status.
    let data: Record<string, unknown> | null = null;
    try {
      data = rawBody ? (JSON.parse(rawBody) as Record<string, unknown>) : null;
    } catch {
      return res.status(400).json({ error: 'Invalid request' });
    }

    if (!data) {
      return res.status(400).json({ error: 'Invalid request' });
    }

    const status = data.status;

    if (status === 'success') {
      const sessionId = data.session_id;
      const encounterId = data.encounter_id;
      const sessions = (data.sessions as unknown[]) || [];
      const additionalInfo = data.additional_info;

      console.log(`Session ${sessionId} completed successfully`);
      console.log(`Encounter ID: ${encounterId}`);
      console.log(`Total sessions: ${sessions.length}`);
      if (additionalInfo) {
        console.log('Additional info:', additionalInfo);
      }

      // Optional follow-up links. Each href is a path; combine with your API base URL
      // and call with the correct authentication for Ambient or Form filling.
      const links = (data._links as Record<string, Array<Record<string, unknown>>>) || {};
      for (const key of [
        'contents',
        'encounter_content',
        'structured_data',
        'encounter_structured_data',
        'status',
        'transcripts',
      ] as const) {
        for (const link of links[key] || []) {
          console.log(
            `${key}: ${link.method} ${link.href} - ${link.name}`,
          );
        }
      }

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

    if (status === 'failure') {
      console.log(`Session ${data.session_id} failed`);
      console.log(`Encounter ID: ${data.encounter_id}`);
      console.log(`Error Code: ${data.error_code}`);
      console.log(`Error Detail: ${data.error_detail}`);
      return res.status(200).json({ message: 'Failure notification received' });
    }

    // Timeout / cancellation (and any other verified delivery): ack so Suki does not retry.
    // Example JSON for those events is not fully published yet; session_id / encounter_id are documented.
    console.log(
      'Acknowledged status=',
      status,
      'session_id=',
      data.session_id,
      'encounter_id=',
      data.encounter_id,
    );
    return res.status(200).json({ message: 'Notification acknowledged' });
  },
);

// Local smoke test only. Production must use public HTTPS.
app.listen(3000, () => {
  // Example local port only — use public HTTPS in production
  console.log('Webhook receiver listening on http://localhost:3000');
});