Electronic Signature API Guide: Architecture, State Machines & 6 Providers (2026)

import express, { Request, Response } from "express";
import crypto from "crypto";

// 1. Dispatch document
export async function sendEmploymentAgreement(name: string, email: string) {
  const response = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.SIGNBEE_API_KEY}`,
    },
    body: JSON.stringify({
      markdown: `# Consulting Agreement\n\nBetween Acme Corp and ${name}...`,
      recipient_name: name,
      recipient_email: email,
      webhook_url: "https://api.yourdomain.com/webhooks/signbee",
    }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Failed to send contract: ${response.status} ${errorText}`);
  }

  return response.json(); // { document_id, signing_url }
}

// 2. Webhook listener with timing-safe HMAC-SHA256 validation
export function createWebhookHandler(webhookSecret: string) {
  return (req: Request, res: Response) => {
    const signature = req.headers["x-signbee-signature"] as string;
    if (!signature) {
      return res.status(401).json({ error: "Missing signature header" });
    }

    const rawBody = (req as any).rawBody || JSON.stringify(req.body);
    const expectedSignature = crypto
      .createHmac("sha256", webhookSecret)
      .update(rawBody)
      .digest("hex");

    // Timing-attack safe comparison
    const sigBuffer = Buffer.from(signature);
    const expectedBuffer = Buffer.from(expectedSignature);

    if (sigBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(sigBuffer, expectedBuffer)) {
      return res.status(403).json({ error: "Invalid HMAC signature" });
    }

    const event = req.body;
    if (event.event === "document.completed") {
      console.log(`Contract ${event.document_id} signed by ${event.recipient_email}`);
      console.log(`Certificate SHA-256 digest: ${event.certificate_hash}`);
      // Update database status: completed
    }

    res.status(200).json({ received: true });
  };
}

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
)

type SignbeeWebhookEvent struct {
	Event      string `json:"event"`
	DocumentID string `json:"document_id"`
	Email      string `json:"recipient_email"`
	CertHash   string `json:"certificate_hash"`
}

func SignbeeWebhookHandler(w http.ResponseWriter, r *http.Request) {
	secret := []byte(os.Getenv("SIGNBEE_WEBHOOK_SECRET"))
	receivedSig := r.Header.Get("X-Signbee-Signature")
	if receivedSig == "" {
		http.Error(w, "Missing signature header", http.StatusUnauthorized)
		return
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Failed to read body", http.StatusBadRequest)
		return
	}
	defer r.Body.Close()

	// Compute HMAC-SHA256
	mac := hmac.New(sha256.New, secret)
	mac.Write(body)
	expectedSig := hex.EncodeToString(mac.Sum(nil))

	// Constant-time comparison prevents timing analysis
	if subtle.ConstantTimeCompare([]byte(receivedSig), []byte(expectedSig)) != 1 {
		http.Error(w, "Forbidden: Invalid signature", http.StatusForbidden)
		return
	}

	var event SignbeeWebhookEvent
	if err := json.Unmarshal(body, &event); err != nil {
		http.Error(w, "Malformed JSON", http.StatusBadRequest)
		return
	}

	if event.Event == "document.completed" {
		log.Printf("Document %s completed! Digest: %s", event.DocumentID, event.CertHash)
	}

	w.WriteHeader(http.StatusOK)
	w.Write([]byte(`{"received": true}`))
}