Verify Webhook HMAC Signature

Problem: Webhook signature checks fail, or you process unverified POSTs after framework JSON parsing rewrites the body. Solution: Sign generated-at + : + the raw body with HMAC-SHA-256 using your partner secret. Compare the hex digest to X-API-Key with a constant-time compare.

This cookbook assumes you already have your webhook secret key from partner onboarding and a HTTPS callback URL.

Python
TypeScript

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", "")
    message = timestamp + ":" + raw_body

    expected = request.headers.get("X-API-Key", "")
    computed = hmac.new(
        secret_key.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(computed, expected):
        return jsonify({"error": "Invalid signature"}), 401

    data = json.loads(raw_body)
    return jsonify({"message": "Notification received"}), 200

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 = req.body.toString("utf8");
    const timestamp = String(req.headers["generated-at"] || "");
    const message = timestamp + ":" + rawBody;

    const expected = String(req.headers["x-api-key"] || "");
    const computed = crypto
      .createHmac("sha256", secretKey)
      .update(message, "utf8")
      .digest("hex");

    const match =
      computed.length === expected.length &&
      crypto.timingSafeEqual(
        Buffer.from(computed, "utf8"),
        Buffer.from(expected, "utf8")
      );

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

    const data = JSON.parse(rawBody);
    return res.status(200).json({ message: "Notification received" });
  }
);

Common mistakes

Auto-parsing JSON before you read the raw body breaks verification.
Do not trim, pretty-print, or re-serialize the body before you sign it.

Other cookbooks

AmbientAPI

Poll Session Status Before Fetching Content

Poll until status is completed.

5 min

AmbientAPI

Fetch Note Content with composition_id

Retrieve the note with composition_id.

5 min

​Common mistakes

​Other cookbooks

​Poll Session Status Before Fetching Content

​Fetch Note Content with composition_id

Common mistakes

Other cookbooks

Poll Session Status Before Fetching Content

Fetch Note Content with composition_id