Cloudflare Workers E-Signature Integration: Sub-10ms Global Dispatches (2026)

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "edge-contract-service",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["nodejs_compat"],
  
  // Cloudflare Workers KV Binding for low-latency URL caching
  "kv_namespaces": [
    {
      "binding": "CONTRACTS_KV",
      "id": "a93b45c83921471ab8e39f82103984e1"
    }
  ],

  // Cloudflare D1 SQLite Database for relational contract records
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "contracts_prod",
      "database_id": "8f830d12-6831-4be2-9b21-39e248b108e4"
    }
  ]
}

# Set your Signbee API Key and Webhook Signing Secret
npx wrangler secret put SIGNBEE_API_KEY
npx wrangler secret put SIGNBEE_WEBHOOK_SECRET

export interface Env {
  // Secrets
  SIGNBEE_API_KEY: string;
  SIGNBEE_WEBHOOK_SECRET: string;

  // Bindings
  CONTRACTS_KV: KVNamespace;
  DB: D1Database;
}

export interface DispatchRequest {
  client_id: string;
  recipient_name: string;
  recipient_email: string;
  company_name: string;
  service_fee: number;
  scope_of_work: string;
}

export interface SignbeeSendResponse {
  id: string;
  status: "draft" | "pending_signature" | "completed" | "expired";
  signing_url: string;
  created_at: string;
}

export interface SignbeeWebhookEvent {
  event: "document.created" | "document.viewed" | "document.signed" | "document.completed";
  data: {
    id: string;
    status: string;
    recipient_email: string;
    signed_at?: string;
    sha256_hash?: string;
    pdf_download_url?: string;
  };
  timestamp: number;
}

import { Env, DispatchRequest, SignbeeSendResponse } from "../types";

export async function handleContractDispatch(
  request: Request,
  env: Env
): Promise<Response> {
  if (request.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  try {
    const body = (await request.json()) as DispatchRequest;

    if (!body.recipient_email || !body.recipient_name || !body.company_name) {
      return Response.json(
        { error: "Missing required contract fields." },
        { status: 400 }
      );
    }

    // 1. Interpolate Markdown Contract Template
    const contractMarkdown = `# Master Services Agreement

**Client:** ${body.company_name}  
**Representative:** ${body.recipient_name} (${body.recipient_email})  
**Effective Date:** ${new Date().toISOString().split("T")[0]}  
**Service Fee:** $${body.service_fee.toLocaleString()} USD  

---

## 1. Scope of Work
${body.scope_of_work}

## 2. Term & Termination
This Agreement shall commence on the Effective Date and remain in effect until the completion of the Services. Either party may terminate with 14 days written notice.

## 3. Execution & Cryptographic Audit
By providing a digital signature below, both parties acknowledge and agree to be bound by the terms set forth herein.
`;

    // 2. Dispatch via native HTTP fetch() to Signbee REST API
    const apiStartTime = performance.now();
    const signbeeResponse = await fetch("https://signb.ee/api/v1/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${env.SIGNBEE_API_KEY}`,
        "User-Agent": "Cloudflare-Worker-Edge-Service/2.0",
      },
      body: JSON.stringify({
        markdown: contractMarkdown,
        recipient_name: body.recipient_name,
        recipient_email: body.recipient_email,
        subject: `Services Agreement for ${body.company_name}`,
        expires_in_days: 14,
      }),
    });

    const latencyMs = Math.round(performance.now() - apiStartTime);

    if (!signbeeResponse.ok) {
      const errText = await signbeeResponse.text();
      return Response.json(
        { error: "Signbee API request failed", details: errText },
        { status: signbeeResponse.status }
      );
    }

    const docData = (await signbeeResponse.json()) as SignbeeSendResponse;

    // 3. Cache Signing URL in Cloudflare KV (Fast Edge Retrieval)
    // TTL of 14 days matching document expiry
    await env.CONTRACTS_KV.put(
      `contract:${docData.id}`,
      JSON.stringify({
        id: docData.id,
        signing_url: docData.signing_url,
        status: docData.status,
        recipient: body.recipient_email,
      }),
      { expirationTtl: 14 * 86400 }
    );

    // 4. Persist Record to Cloudflare D1 SQLite Database
    await env.DB.prepare(`
      INSERT INTO contracts (id, client_id, recipient_name, recipient_email, status, signing_url, dispatch_latency_ms, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
    `).bind(
      docData.id,
      body.client_id,
      body.recipient_name,
      body.recipient_email,
      docData.status,
      docData.signing_url,
      latencyMs
    ).run();

    return Response.json(
      {
        success: true,
        contract_id: docData.id,
        signing_url: docData.signing_url,
        status: docData.status,
        edge_dispatch_latency_ms: latencyMs,
      },
      { status: 201 }
    );
  } catch (error: any) {
    return Response.json(
      { error: "Internal edge worker error", message: error.message },
      { status: 500 }
    );
  }
}

/**
 * Verifies an HMAC-SHA256 webhook signature using Web Crypto (crypto.subtle).
 * Operates in constant-time to eliminate timing attack vectors.
 */
export async function verifyWebhookSignature(
  secret: string,
  rawBody: string,
  signatureHeader: string | null
): Promise<boolean> {
  if (!signatureHeader || !secret) {
    return false;
  }

  try {
    const encoder = new TextEncoder();
    const keyData = encoder.encode(secret);
    const bodyData = encoder.encode(rawBody);

    // 1. Import Secret as HMAC-SHA256 CryptoKey
    const cryptoKey = await crypto.subtle.importKey(
      "raw",
      keyData,
      { name: "HMAC", hash: "SHA-256" },
      false,
      ["sign", "verify"]
    );

    // 2. Normalize hex signature into binary Uint8Array
    const cleanSignature = signatureHeader.replace(/^sha256=/, "").trim();
    if (cleanSignature.length !== 64) {
      return false;
    }

    const signatureBytes = new Uint8Array(
      cleanSignature.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []
    );

    // 3. Verify signature using native Web Crypto verify()
    const isValid = await crypto.subtle.verify(
      "HMAC",
      cryptoKey,
      signatureBytes,
      bodyData
    );

    return isValid;
  } catch (err) {
    console.error("Web Crypto verification error:", err);
    return false;
  }
}

import { Env, SignbeeWebhookEvent } from "../types";
import { verifyWebhookSignature } from "../utils/crypto";

export async function handleWebhook(
  request: Request,
  env: Env
): Promise<Response> {
  if (request.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  // 1. Read raw body as text for HMAC verification
  const rawBody = await request.text();
  const signatureHeader = request.headers.get("X-Signbee-Signature");

  const isVerified = await verifyWebhookSignature(
    env.SIGNBEE_WEBHOOK_SECRET,
    rawBody,
    signatureHeader
  );

  if (!isVerified) {
    return Response.json(
      { error: "Invalid cryptographic webhook signature." },
      { status: 401 }
    );
  }

  // 2. Parse verified payload
  const event = JSON.parse(rawBody) as SignbeeWebhookEvent;

  // 3. Process Signature Completion Events
  if (event.event === "document.signed" || event.event === "document.completed") {
    const { id, status, signed_at, sha256_hash, pdf_download_url } = event.data;

    // Update Cloudflare D1 SQL Record
    await env.DB.prepare(`
      UPDATE contracts
      SET status = ?,
          signed_at = ?,
          sha256_audit_hash = ?,
          pdf_url = ?,
          updated_at = datetime('now')
      WHERE id = ?
    `).bind(
      status,
      signed_at || new Date().toISOString(),
      sha256_hash || null,
      pdf_download_url || null,
      id
    ).run();

    // Refresh KV Cache with Final State
    const cached = await env.CONTRACTS_KV.get(`contract:${id}`);
    if (cached) {
      const parsed = JSON.parse(cached);
      parsed.status = status;
      parsed.pdf_url = pdf_download_url;
      await env.CONTRACTS_KV.put(`contract:${id}`, JSON.stringify(parsed), {
        expirationTtl: 30 * 86400,
      });
    }
  }

  return Response.json({ received: true, event: event.event }, { status: 200 });
}

import { Env } from "./types";
import { handleContractDispatch } from "./handlers/dispatch";
import { handleWebhook } from "./handlers/webhook";

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    // Route: POST /api/contracts/dispatch
    if (url.pathname === "/api/contracts/dispatch") {
      return handleContractDispatch(request, env);
    }

    // Route: POST /api/webhooks/signbee
    if (url.pathname === "/api/webhooks/signbee") {
      return handleWebhook(request, env);
    }

    // Route: GET /api/contracts/:id (Sub-millisecond KV Read)
    if (url.pathname.startsWith("/api/contracts/") && request.method === "GET") {
      const contractId = url.pathname.split("/")[3];
      const cached = await env.CONTRACTS_KV.get(`contract:${contractId}`);
      
      if (!cached) {
        return Response.json({ error: "Contract not found" }, { status: 404 });
      }

      return new Response(cached, {
        headers: { "Content-Type": "application/json", "Cache-Control": "public, max-age=60" },
      });
    }

    return new Response("Not Found", { status: 404 });
  },
};