Build Webhook Notification Receiver

What you will build

10 min | Beginner

An HTTPS webhook endpoint for partner notifications.
Signature checks on the raw request body before you parse JSON.
Handling for success and failure notifications.
Reject invalid signatures and acknowledge valid notifications.

Using an AI coding tool?Copy the prompt below to point your agent at the webhooks skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the webhooks skill and connect the documentation MCP.

Open in Cursor

In this tutorial, you build a server-side webhook receiver for Suki partner notifications. You verify each request with HMAC-SHA-256, parse the JSON body only after verification succeeds, and branch on SUCCESS or FAILURE. Examples are provided in Python and TypeScript coding languages. By the end of this tutorial, you’ll have a working POST /webhooks/notification handler that rejects invalid signatures with 4xx and acknowledges accepted notifications with 2xx.

Prerequisites

Before you begin, make sure you have:

Completed Partner onboarding.
Shared your HTTPS callback URL with Suki so it is stored on your partner record. You cannot register or change this URL through a self-service API. See Configuration.
Your partner secret key from Suki (server-side only).
A publicly reachable HTTPS endpoint (TLS 1.2 or higher).
An integration that creates and ends ambient or Form filling sessions so Suki can send completion or failure events. Refer to Build ambient session Streaming Client or Build Form filling Session Client tutorials for examples.

Store your partner secret key only on your backend. Never expose it in a client-side or public application.

Architecture

Project setup

Create a script or server project in the language used by this tutorial (Python or TypeScript).
Install the required dependencies:.
- Python: pip install flask.
- TypeScript: npm install express.
Configure your credentials:.
- Store your partner secret key on your backend only. Never expose it in browser code.
Expose POST /webhooks/notification (or the path you registered with Suki) on a publicly reachable HTTPS URL.

How signature verification works in this tutorial

Piece	Role
Partner secret key	HMAC key from onboarding
`generated-at`	Unix time in milliseconds, used in the signed string
Raw body	Exact bytes or string Suki sent (no pretty-print, trim, or re-serialize)
Signed string	`generated-at` + `:` + raw body
`X-API-Key`	Expected hex HMAC digest to compare against

Important points to remember:

Verify against the raw body before JSON parse. Pretty-print, trim, or auto-parse middleware changes bytes and breaks HMAC.
Reject requests that are missing X-API-Key or have an empty digest with 4xx.
Return 2xx for accepted notifications after you verify the signature.
Confirm the HTTPS callback URL is registered with Suki on your partner record.

Tutorial steps

Work through each step in order. Read the explanation, review the code example, then continue to the next step. The full code example is available in the accordion below.

Accept the POST Callback

Expose an HTTPS POST route that matches the callback URL you shared with Suki. Keep the partner secret key on your backend only.Check: Your HTTPS POST route matches the callback URL registered with Suki.

@app.route("/webhooks/notification", methods=["POST"])
def handle_webhook():
# Handle the partner notification here.
...

app.post(
'/webhooks/notification',
express.raw({ type: 'application/json' }),
(req, res) => {
// Handle the partner notification here.
},
);

Read the Raw Body and Headers

Read the raw request body before JSON parsing, plus the generated-at and X-API-Key headers. See Verify signatures.Check: You hold the raw body bytes plus generated-at and X-API-Key before any JSON parse.

raw_body = request.get_data(as_text=True)
timestamp = request.headers.get("generated-at", "")
message = timestamp + ":" + raw_body
expected_signature_hex = request.headers.get("X-API-Key", "")

const rawBody = Buffer.isBuffer(req.body)
? req.body.toString('utf8')
: String(req.body ?? '');
const timestamp = String(req.headers['generated-at'] ?? '');
const message = `${timestamp}:${rawBody}`;
const expectedSignatureHex = String(req.headers['x-api-key'] ?? '');

Verify the HMAC Signature

Recompute HMAC-SHA-256 over generated-at + : + raw body, encode as hex, and compare to X-API-Key with a constant-time compare.Check: Invalid signatures return 401. Valid signatures pass a constant-time compare.If it fails: Verify against the raw request body before you parse JSON. Verifying a re-serialized body will not match.

computed_signature_hex = hmac.new(
SECRET_KEY.encode("utf-8"),
message.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

const computedSignatureHex = crypto
.createHmac('sha256', SECRET_KEY)
.update(message, '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' });
}

Parse JSON and Branch on Status

Only after verification succeeds, parse JSON and branch on top-level status. Documented example payloads use SUCCESS and FAILURE. Acknowledge every verified delivery with 2xx. See Payload and response and Event types.Check: You parse JSON only after verification, and you branch on SUCCESS and FAILURE.

data = json.loads(raw_body)
status = data.get("status")

if status == "SUCCESS":
session_id = data.get("session_id")
# Process success notification...
elif status == "FAILURE":
error_code = data.get("error_code")
# Process failure notification...

const data = JSON.parse(rawBody) as Record<string, unknown>;
const status = data.status;

if (status === 'SUCCESS') {
// Process success notification...
} else if (status === 'FAILURE') {
// Process failure notification...
}

Return 2xx

Return 200 (or another 2xx) so Suki treats the notification as delivered. Invalid signatures should stay 401 (or 400).Check: Accepted notifications return 2xx. Invalid signatures stay 401 (or 400).If it fails: Return 2xx for accepted notifications after you verify the signature. If you do not, Suki keeps retrying the delivery.

if status == "SUCCESS":
return jsonify({"message": "Notification received"}), 200

if status == "FAILURE":
return jsonify({"message": "Failure notification received"}), 200

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

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

if (status === 'FAILURE') {
return res.status(200).json({ message: 'Failure notification received' });
}

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

Full code example

Python

# Webhook notification tutorial (Python)
# Flow: read raw body → verify HMAC-SHA-256 → parse JSON → branch on status → return 2xx
# Install: pip install flask

import hashlib
import hmac
import json

from flask import Flask, jsonify, request

app = Flask(__name__)

# ---------------------------------------------------------------------------
# Replace with your partner secret key from onboarding (server-side only)
# ---------------------------------------------------------------------------
SECRET_KEY = "<partner_secret_key>"  # Example only — replace with your partner webhook secret from onboarding

@app.route("/webhooks/notification", methods=["POST"])
def handle_webhook():
    # 1) Read the raw body exactly as Suki sent it (before JSON parsing).
    raw_body = request.get_data(as_text=True)
    timestamp = request.headers.get("generated-at", "")
    message = timestamp + ":" + raw_body

    # 2) Recompute HMAC-SHA-256 and compare to X-API-Key (constant-time).
    expected_signature_hex = request.headers.get("X-API-Key", "")
    computed_signature_hex = hmac.new(
        SECRET_KEY.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    # Reject missing signatures before compare (empty header must not verify).
    if not expected_signature_hex or not hmac.compare_digest(
        computed_signature_hex, expected_signature_hex
    ):
        return jsonify({"error": "Invalid signature"}), 401

    # 3) Signature matched. Safe to parse JSON and branch on status.
    try:
        data = json.loads(raw_body) if raw_body else None
    except json.JSONDecodeError:
        return jsonify({"error": "Invalid request"}), 400

    if not data or not isinstance(data, dict):
        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")
        sessions = data.get("sessions", [])
        additional_info = data.get("additional_info")

        print(f"Session {session_id} completed successfully")
        print(f"Encounter ID: {encounter_id}")
        print(f"Total sessions: {len(sessions)}")
        if additional_info:
            print(f"Additional info: {additional_info}")

        # 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.
        links = data.get("_links") or {}
        for key in (
            "contents",
            "encounter_content",
            "structured_data",
            "encounter_structured_data",
            "status",
            "transcripts",
        ):
            for link in links.get(key) or []:
                print(
                    f"{key}: {link.get('method')} {link.get('href')} - {link.get('name')}"
                )

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

    if status == "FAILURE":
        session_id = data.get("session_id")
        encounter_id = data.get("encounter_id")
        error_code = data.get("error_code")
        error_detail = data.get("error_detail")

        print(f"Session {session_id} failed")
        print(f"Encounter ID: {encounter_id}")
        print(f"Error Code: {error_code}")
        print(f"Error Detail: {error_detail}")

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

    # Other verified deliveries (for example CKG state payloads): ack so Suki does not retry.
    print(
        f"Acknowledged status={status!r} "
        f"session_id={data.get('session_id')} encounter_id={data.get('encounter_id')}"
    )
    return jsonify({"message": "Notification acknowledged"}), 200

if __name__ == "__main__":
    # Local smoke test only. Production must use public HTTPS.
    app.run(port=3000)  # Example local port only — use public HTTPS in production

TypeScript

// 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' });
    }

    // Other verified deliveries (for example CKG state payloads): ack so Suki does not retry.
    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');
});

Troubleshooting

Signatures Never Match

Verify against the raw body before JSON parse. Pretty-print, trim, or auto-parse middleware changes bytes and breaks HMAC.

Missing X-API-Key or Empty Digest

Reject with 4xx. Do not call a constant-time compare on an empty expected signature as a successful verify.

Suki Keeps Retrying

Return 2xx for accepted notifications after you verify the signature (see Event types).

No Callbacks Arrive

Confirm the HTTPS URL is registered with Suki on your partner record (Configuration).

Summary

In this tutorial, you:

Built a POST /webhooks/notification handler.
Verified each request with HMAC-SHA-256 before parsing JSON.
Branched on SUCCESS or FAILURE and returned 2xx for accepted events.

Keep the partner secret server-side only.

Streaming

SDKs

Webhook

Build Webhook Notification Receiver

Prerequisites

Architecture

Project setup

How signature verification works in this tutorial

Tutorial steps

Full code example

Troubleshooting

Summary

Other tutorials

​Prerequisites

​Architecture

​Project setup

​How signature verification works in this tutorial

​Tutorial steps

​Full code example

​Troubleshooting

​Summary

​Other tutorials

Prerequisites

Architecture

Project setup

How signature verification works in this tutorial

Tutorial steps

Full code example

Troubleshooting

Summary

Other tutorials