Nuxt 4 & Nitro Server Routes: Add E-Signatures in 10 Minutes (2026)

// nuxt.config.ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
  runtimeConfig: {
    // Private server-only secrets (never bundled into client code)
    // Automatically overridden at runtime by NUXT_SIGNBEE_API_KEY
    // and NUXT_SIGNBEE_WEBHOOK_SECRET environment variables
    signbeeApiKey: "",
    signbeeWebhookSecret: "",
    signbeeSenderName: "Acme Cloud Legal",
    signbeeSenderEmail: "contracts@acmecloud.io",

    // Public keys exposed to Vue components via useRuntimeConfig().public
    public: {
      appUrl: "https://portal.acmecloud.io",
    },
  },
  devtools: { enabled: true },
});

// .env (Local Development — Never commit to Git)
// NUXT_SIGNBEE_API_KEY="signbee_live_9f8e7d6c5b4a3f2e1d0c"
// NUXT_SIGNBEE_WEBHOOK_SECRET="whsec_4a5b6c7d8e9f0a1b2c3d4e5f"

// server/api/contracts/send.post.ts
import { z } from "zod";
import { defineEventHandler, readValidatedBody, createError } from "h3";

const SendContractSchema = z.object({
  clientCompany: z.string().min(2, "Company name is required").max(120),
  recipientName: z.string().min(2, "Recipient name is required").max(100),
  recipientEmail: z.string().email("Valid recipient email is required"),
  planTier: z.enum(["Growth", "Scale", "Enterprise"]),
  annualSeats: z.number().int().min(1).max(10000),
  annualValueUsd: z.number().positive(),
  customTerms: z.string().max(2000).optional(),
});

interface SignbeeSendResponse {
  id: string;
  status: "sent" | "pending_verification";
  title: string;
  signing_url?: string;
  verify_url: string;
  created_at: string;
}

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);

  if (!config.signbeeApiKey) {
    throw createError({
      statusCode: 500,
      statusMessage: "Server configuration error: missing NUXT_SIGNBEE_API_KEY",
    });
  }

  // Validate request body with H3 + Zod
  const payload = await readValidatedBody(event, (body) =>
    SendContractSchema.parse(body)
  );

  const effectiveDate = new Date().toISOString().split("T")[0];
  const formattedPrice = new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: "USD",
  }).format(payload.annualValueUsd);

  // Compile clean CommonMark markdown (Signbee renders tables, headers & pagination into A4 PDF)
  const contractMarkdown = [
    `# Master SaaS Subscription Agreement — ${payload.clientCompany}`,
    "",
    `This Subscription Agreement ("Agreement") is entered into on **${effectiveDate}** between **${config.signbeeSenderName}** ("Provider") and **${payload.clientCompany}** ("Customer").`,
    "",
    "## 1. Subscription Order Schedule",
    "",
    "| Subscription Tier | Licensed Seats | Billing Cycle | Annual Contract Value |",
    "| :--- | :--- | :--- | :--- |",
    `| ${payload.planTier} Plan | ${payload.annualSeats} Seats | Annual Upfront | ${formattedPrice} |`,
    "",
    "## 2. Service Level & Data Protection",
    "Provider guarantees 99.95% monthly uptime across all production API endpoints and processes all personal data in strict accordance with the UK GDPR, EU GDPR, and standard contractual clauses.",
    "",
    payload.customTerms
      ? `## 3. Special Commercial Addendum\n\n${payload.customTerms}`
      : "## 3. Standard Commercial Terms\n\nThis Order Form is governed by the standard Master Terms published at portal.acmecloud.io/legal.",
    "",
    "## 4. Electronic Execution",
    "By executing this Agreement below, both parties acknowledge and agree that electronic signatures carry the same legal enforceability and admissibility as handwritten signatures under the US ESIGN Act, eIDAS, and the UK Electronic Communications Act 2000.",
  ].join("\n");

  try {
    const response = await $fetch<SignbeeSendResponse>(
      "https://signb.ee/api/v1/send",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${config.signbeeApiKey}`,
          "Content-Type": "application/json",
        },
        body: {
          title: `SaaS Subscription Agreement — ${payload.clientCompany}`,
          markdown: contractMarkdown,
          sender_name: config.signbeeSenderName,
          sender_email: config.signbeeSenderEmail,
          recipient_name: payload.recipientName,
          recipient_email: payload.recipientEmail,
          expires_in_days: 14,
          webhook_url: `${config.public.appUrl}/api/webhooks/signbee`,
        },
      }
    );

    return {
      ok: true,
      documentId: response.id,
      status: response.status,
      verifyUrl: response.verify_url,
      dispatchedAt: response.created_at,
    };
  } catch (err: any) {
    throw createError({
      statusCode: err?.response?.status || 502,
      statusMessage:
        err?.data?.error || "Failed to dispatch agreement via Signbee API",
    });
  }
});

// app/components/ContractDispatcher.vue (Vue 3 Setup Script & Template)
import { reactive, ref } from "vue";

const form = reactive({
  clientCompany: "Northwind Logistics Ltd",
  recipientName: "Elena Rostova",
  recipientEmail: "elena@northwind.io",
  planTier: "Scale" as const,
  annualSeats: 25,
  annualValueUsd: 18500,
  customTerms: "Includes dedicated SSO configuration and quarterly architecture reviews.",
});

const isSubmitting = ref(false);
const errorMessage = ref<string | null>(null);
const dispatchResult = ref<{
  documentId: string;
  verifyUrl: string;
  dispatchedAt: string;
} | null>(null);

export async function handleSendAgreement() {
  isSubmitting.value = true;
  errorMessage.value = null;

  try {
    const result = await $fetch("/api/contracts/send", {
      method: "POST",
      body: form,
    });
    dispatchResult.value = {
      documentId: result.documentId,
      verifyUrl: result.verifyUrl,
      dispatchedAt: result.dispatchedAt,
    };
  } catch (err: any) {
    errorMessage.value =
      err?.data?.statusMessage || "Unable to send contract for signature.";
  } finally {
    isSubmitting.value = false;
  }
}

/*
<template>
  <div class="p-6 rounded-2xl bg-zinc-900 border border-zinc-800 max-w-xl">
    <h3 class="text-lg font-bold text-zinc-100 mb-4">
      Dispatch Enterprise Order Form
    </h3>

    <form @submit.prevent="handleSendAgreement" class="space-y-4">
      <div>
        <label class="block text-xs font-mono text-zinc-400 mb-1">Client Company</label>
        <input v-model="form.clientCompany" required class="w-full px-3 py-2 rounded-lg bg-zinc-950 border border-zinc-800 text-zinc-100 text-sm" />
      </div>

      <div class="grid grid-cols-2 gap-3">
        <div>
          <label class="block text-xs font-mono text-zinc-400 mb-1">Signer Name</label>
          <input v-model="form.recipientName" required class="w-full px-3 py-2 rounded-lg bg-zinc-950 border border-zinc-800 text-zinc-100 text-sm" />
        </div>
        <div>
          <label class="block text-xs font-mono text-zinc-400 mb-1">Signer Email</label>
          <input v-model="form.recipientEmail" type="email" required class="w-full px-3 py-2 rounded-lg bg-zinc-950 border border-zinc-800 text-zinc-100 text-sm" />
        </div>
      </div>

      <button
        type="submit"
        :disabled="isSubmitting"
        class="w-full py-2.5 px-4 rounded-lg bg-amber-500 text-zinc-950 font-semibold text-sm hover:bg-amber-400 disabled:opacity-50"
      >
        {{ isSubmitting ? "Generating PDF & Dispatching..." : "Send Legally Binding Contract" }}
      </button>
    </form>

    <div v-if="dispatchResult" class="mt-4 p-4 rounded-xl bg-emerald-950/30 border border-emerald-500/30 text-xs text-emerald-300">
      Agreement dispatched! Document ID: {{ dispatchResult.documentId }}
    </div>
  </div>
</template>
*/

// server/api/webhooks/signbee.post.ts
import { createHmac, timingSafeEqual } from "node:crypto";
import { defineEventHandler, readRawBody, getHeader, createError } from "h3";

interface SignbeeWebhookEvent {
  event: "document.sent" | "document.viewed" | "document.signed" | "document.expired";
  document_id: string;
  title: string;
  recipient_email: string;
  signed_at?: string;
  sha256_hash?: string;
  signed_pdf_url?: string;
  verify_url: string;
}

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);
  const signatureHeader = getHeader(event, "x-signbee-signature");

  if (!signatureHeader || !config.signbeeWebhookSecret) {
    throw createError({
      statusCode: 401,
      statusMessage: "Missing webhook signature or secret configuration",
    });
  }

  // CRITICAL: Read raw unparsed UTF-8 bytes before any JSON parsing
  const rawBody = await readRawBody(event, "utf8");
  if (!rawBody) {
    throw createError({
      statusCode: 400,
      statusMessage: "Empty webhook payload",
    });
  }

  // Compute expected HMAC-SHA256 signature
  const expectedSignature = createHmac("sha256", config.signbeeWebhookSecret)
    .update(rawBody, "utf8")
    .digest("hex");

  const cleanProvided = signatureHeader.replace(/^sha256=/, "");
  const providedBuffer = Buffer.from(cleanProvided, "hex");
  const expectedBuffer = Buffer.from(expectedSignature, "hex");

  if (
    providedBuffer.length !== expectedBuffer.length ||
    !timingSafeEqual(providedBuffer, expectedBuffer)
  ) {
    throw createError({
      statusCode: 401,
      statusMessage: "Invalid X-Signbee-Signature digest",
    });
  }

  // Safe to parse JSON after cryptographic verification passes
  const payload = JSON.parse(rawBody) as SignbeeWebhookEvent;

  if (payload.event === "document.signed") {
    // Idempotently update tenant status in your database (Drizzle / Prisma)
    console.info(
      `[Signbee Webhook] Document ${payload.document_id} signed by ${payload.recipient_email}. SHA-256: ${payload.sha256_hash}`
    );
  }

  return { received: true, documentId: payload.document_id };
});