Webhook Signature Verification

Verify Webhook request signatures with HMAC, X-API-Key, and generated-at headers before processing callback payloads

When Suki makes a webhook request to your callback URL, it includes a signature that allows your application to verify that the request originated from Suki and that the request body was not modified in transit.

Verify the Webhook request signature before parsing the JSON request body. Processing unverified requests can expose your integration to spoofed requests and tampered payloads.

What you need to verify the Webhook request signature

To verify the Webhook request signature, you need the following:

Component	Description
Secret key	A password-like string Suki puts on your partner record and shares with you during partner onboarding. Only your server should know it.
generated-at header	A number: Unix time in milliseconds when Suki built this request. You need it as part of the signed text.
X-API-Key header	The expected signature for this request, already turned into hex text. Your job is to compute the same hex and see if they are equal.

Suki sends each notification as a POST with Content-Type: application/json. Your handler reads the raw body and the two headers above before you trust the payload.

How to verify the Webhook request signature on your server

Perform the following steps on your application server to verify the Webhook request signature:

1. Read the Raw Body First

   Read the request body before you parse JSON. Keep the exact bytes or string Suki sent (no pretty-printing, no trimming, no changing spaces).

2. Read the Generated-At Header

   Read the generated-at header exactly as the string Suki sent (the millisecond timestamp).

   The webhook rejects requests where the generated-at timestamp is older than two minutes to prevent replay attacks.

3. Build the String to Sign

   Join generated-at + : + raw body into one long string. Example shape: 1765977748432:{"status":"success",...} (your timestamp and JSON will differ).

4. Run HMAC-SHA-256

   Run HMAC-SHA-256 using your secret key as the key and that long string as the data. HMAC-SHA-256 is a standard “sign this text with this secret” operation; every language has a library for it.

5. Encode the Digest as Hex

   Turn the HMAC output into hex the same way Suki does (usually lowercase hex; if your comparison fails, ask your Suki contact whether casing matters).

6. Compare to X-API-Key

   Compare your hex to the X-API-Key header. Use a constant-time compare if your framework offers one, so attackers cannot guess the signature byte by byte.

If the values do not match, stop and return 4xx. If they match, you can safely parse the JSON and run your business logic.

Pseudocode

raw_body = read request body as received (string or bytes)
timestamp = request header "generated-at" exactly as sent
message = timestamp + ":" + raw_body

expected_signature_hex = request header "X-API-Key"
computed_signature_hex = hex( HMAC_SHA256(key = secret_key, data = message) )

if not constant_time_equal(computed_signature_hex, expected_signature_hex):
    return 401 or 400
# else: parse JSON and continue

Read the raw request body before JSON parsing. Framework middleware that auto-parses JSON first will break verification because the signature covers the exact bytes Suki sent.

Code examples

The examples below follow the pseudocode above line for line.

Python

Python

import hashlib
import hmac
import json

from flask import Flask, jsonify, request

app = Flask(__name__)

# Partner secret key from onboarding
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", "")
    message = timestamp + ":" + raw_body

    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()

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

    # else: parse JSON and continue
    data = json.loads(raw_body)
    return jsonify({"message": "Notification received"}), 200

TypeScript

TypeScript

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

const app = express();

// Partner secret key from onboarding
const secret_key = "<partner_secret_key>";

app.post("/webhooks/notification", express.raw({ type: "application/json" }), (req, res) => {
  const raw_body = req.body.toString("utf8");
  const timestamp = req.headers["generated-at"] as string;
  const message = timestamp + ":" + raw_body;

  const expected_signature_hex = req.headers["x-api-key"] as string;
  const computed_signature_hex = crypto
    .createHmac("sha256", secret_key)
    .update(message, "utf8")
    .digest("hex");

  const signatures_match =
    computed_signature_hex.length === expected_signature_hex.length &&
    crypto.timingSafeEqual(
      Buffer.from(computed_signature_hex, "utf8"),
      Buffer.from(expected_signature_hex, "utf8"),
    );

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

  // else: parse JSON and continue
  const data = JSON.parse(raw_body);
  return res.status(200).json({ message: "Notification received" });
});

For a full handler that branches on status and processes _links, refer to the Asynchronous notifications (Webhook) API reference.

After verification

After verifying the Webhook signature, parse the JSON request body and handle the notification based on its type:

1. Ambient session notifications: Read the top-level status field to determine the session outcome. Use the session_id, encounter_id, and _links fields to process the event.
2. CKG data ingestion notifications: Read the state field to determine the ingestion outcome. Use the transaction_id and correlation_id fields to identify and track the ingestion job.

For the complete payload schema and field descriptions, refer to Payload & response guide.

Return a 2xx response (for example, 200 OK) after successfully receiving and validating the webhook. This tells Suki the notification was delivered. Process any follow-up work, such as API calls or database updates, after returning the response.

Security best practices

Verify Requests Are from Suki

Implement HMAC-SHA-256 verification using your secret key, the generated-at header, the raw body, and the X-API-Key header as described above.

Validate the Payload

After the signature matches, check the JSON shape and status. Reject malformed or unverified requests with an appropriate 4xx response.

Store the Secret Key Securely

Keep the partner secret key in a secrets manager (for example AWS Secrets Manager or Azure Key Vault), not in source control.

Use HTTPS Only

Your callback URL must use HTTPS with TLS 1.2 or higher. Suki will not send Webhooks to HTTP URLs. See Configuration.

For platform-wide guidance, refer to Security & best practices and Authentication FAQs.

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

Refer to Payload & response for payload structure, example JSON bodies, implementation tips, and follow-up API response codes.

Refer to Event types for session completion, failure, timeout, and cancellation events.