We Shipped Webhooks: Why We Built a One-Event Architecture

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

const app = express();

// Capture raw body buffer for accurate HMAC hashing
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/signbee", (req, res) => {
  const signature = req.headers["x-signbee-signature"] as string;
  const webhookSecret = process.env.SIGNBEE_WEBHOOK_SECRET!;

  if (!signature) {
    return res.status(401).send("Missing signature header");
  }

  // Compute expected HMAC digest from raw buffer
  const expectedHash = crypto
    .createHmac("sha256", webhookSecret)
    .update(req.body)
    .digest("hex");

  const expectedBuffer = Buffer.from(expectedHash, "utf8");
  const signatureBuffer = Buffer.from(signature, "utf8");

  // Constant-time comparison prevents side-channel timing attacks
  if (
    expectedBuffer.length !== signatureBuffer.length ||
    !crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
  ) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(req.body.toString("utf8"));
  console.log(`✅ Verified completion for document ${payload.document_id}`);
  console.log(`PDF Download URL: ${payload.signed_pdf_url}`);
  console.log(`SHA-256 Digest: ${payload.signature_hash}`);

  // Respond immediately with 200 OK
  res.status(200).json({ received: true });
});

from fastapi import FastAPI, Request, HTTPException, status
import hmac
import hashlib
import os

app = FastAPI()
WEBHOOK_SECRET = os.environ["SIGNBEE_WEBHOOK_SECRET"].encode("utf-8")

@app.post("/webhooks/signbee", status_code=status.HTTP_200_OK)
async def handle_signbee_webhook(request: Request):
    signature = request.headers.get("x-signbee-signature")
    if not signature:
        raise HTTPException(status_code=401, detail="Missing signature header")

    # Read raw body bytes to compute HMAC-SHA256
    raw_body = await request.body()
    computed_digest = hmac.new(
        WEBHOOK_SECRET,
        raw_body,
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison prevents side-channel timing leaks
    if not hmac.compare_digest(computed_digest, signature):
        raise HTTPException(status_code=401, detail="Invalid cryptographic signature")

    payload = await request.json()
    doc_id = payload.get("document_id")
    pdf_url = payload.get("signed_pdf_url")
    cert_hash = payload.get("signature_hash")

    # Dispatch to background task or message broker
    print(f"Verified contract completion: {doc_id} with SHA-256 seal {cert_hash}")
    return {"received": True, "document_id": doc_id}

{
  "event": "document.signed",
  "document_id": "doc_8f492b7194ab",
  "status": "completed",
  "created_at": "2026-09-04T14:15:22.000Z",
  "completed_at": "2026-09-04T14:18:47.000Z",
  "title": "Master Services Agreement — Acme Corp",
  "signed_pdf_url": "https://api.signb.ee/v1/documents/doc_8f492b7194ab/download?token=ephemeral_38f29...",
  "certificate_url": "https://api.signb.ee/v1/documents/doc_8f492b7194ab/certificate?token=ephemeral_38f29...",
  "signature_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "counterparties": [
    {
      "email": "sarah@acmecorp.com",
      "name": "Sarah Connor",
      "role": "signer_1",
      "signed_at": "2026-09-04T14:16:10.000Z",
      "ip_address": "198.51.100.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
    },
    {
      "email": "finance@provider.com",
      "name": "Alex Miller",
      "role": "signer_2",
      "signed_at": "2026-09-04T14:18:47.000Z",
      "ip_address": "203.0.113.19",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
    }
  ],
  "metadata": {
    "deal_id": "crm_98124",
    "account_tier": "enterprise"
  }
}

| Item Description                     | Units | Unit Price | Total Amount |
|--------------------------------------|-------|------------|--------------|
| Cloud Architecture Audit             | 1     | $3,500.00  | $3,500.00    |
| Multi-Agent MCP Server Integration   | 1     | $4,500.00  | $4,500.00    |
| Annual Infrastructure SLA Support   | 12    | $250.00    | $3,000.00    |