Documenso Reference Architecture

Overview

Production-ready architecture for Documenso document signing integrations. Covers project layout, layered service architecture, webhook processing, and data flow.

Prerequisites

• Understanding of layered architecture principles
• Documenso SDK knowledge (see documenso-sdk-patterns)
• TypeScript project with Node.js 18+

Recommended Project Structure

my-signing-app/
├── src/
│   ├── documenso/
│   │   ├── client.ts              # Singleton SDK client
│   │   ├── errors.ts              # Custom error classes
│   │   ├── retry.ts               # Retry/backoff logic
│   │   └── types.ts               # Shared types
│   ├── services/
│   │   ├── document-service.ts    # Document CRUD operations
│   │   ├── template-service.ts    # Template-based workflows
│   │   └── signing-service.ts     # Orchestrates signing flows
│   ├── webhooks/
│   │   ├── handler.ts             # Express webhook router
│   │   ├── verify.ts              # Secret verification
│   │   └── processors/
│   │       ├── document-completed.ts
│   │       ├── document-signed.ts
│   │       └── document-rejected.ts
│   ├── api/
│   │   ├── health.ts              # Health check endpoint
│   │   └── routes.ts              # API routes
│   └── config/
│       └── index.ts               # Environment configuration
├── scripts/
│   ├── verify-connection.ts       # Quick health check
│   ├── create-test-doc.ts         # Test document generator
│   └── cleanup-test-docs.ts       # Test data cleanup
├── tests/
│   ├── unit/
│   │   └── document-service.test.ts
│   ├── integration/
│   │   └── document-lifecycle.test.ts
│   └── mocks/
│       └── documenso.ts           # Mock client factory
├── .env.development
├── .env.production
├── docker-compose.yml             # Self-hosted Documenso (dev)
└── package.json

Layer Architecture

┌─────────────────────────────────────────────────────────┐
│  API / Controllers                                       │
│  Routes, request validation, response formatting         │
├─────────────────────────────────────────────────────────┤
│  Service Layer                                           │
│  Business logic, orchestration, authorization            │
│  (document-service, template-service, signing-service)   │
├─────────────────────────────────────────────────────────┤
│  Documenso Client Layer                                  │
│  SDK wrapper, retry, error handling, caching             │
│  (client.ts, retry.ts, errors.ts)                       │
├─────────────────────────────────────────────────────────┤
│  External Services                                       │
│  Documenso API, S3/GCS storage, email, database         │
└─────────────────────────────────────────────────────────┘

Rules:

• Controllers never call Documenso directly -- alw

Documenso Security Basics

Overview

Essential security practices for Documenso integrations: API key management, webhook verification, document access control, and self-hosted signing certificate configuration.

Prerequisites

• Documenso account with API access
• Understanding of environment variables and secret management
• Completed documenso-install-auth setup

Instructions

Step 1: API Key Security

// NEVER hardcode keys
const BAD = new Documenso({ apiKey: "api_abc123..." }); // Exposed in source

// ALWAYS use environment variables
const GOOD = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

Key management rules:

• Store in .env (never committed) or a secrets manager (Vault, AWS Secrets Manager)
• Use team-scoped keys for team resources, personal keys for personal documents
• Rotate keys on employee offboarding -- revoke in dashboard immediately
• CI/CD: use masked/encrypted secrets (GitHub Secrets, GitLab CI variables)

# .gitignore — always include
.env
.env.*
!.env.example

Step 2: Key Rotation with Zero Downtime

// Support dual keys during rotation
function getApiKey(): string {
  // Try primary first, fall back to secondary during rotation
  return process.env.DOCUMENSO_API_KEY_PRIMARY
    ?? process.env.DOCUMENSO_API_KEY_SECONDARY
    ?? (() => { throw new Error("No Documenso API key configured"); })();
}

// Rotation procedure:
// 1. Generate new key in Documenso dashboard
// 2. Set as DOCUMENSO_API_KEY_SECONDARY, deploy
// 3. Verify secondary key works
// 4. Move secondary to PRIMARY, deploy
// 5. Revoke old key in dashboard

Step 3: Webhook Secret Verification

import { timingSafeEqual } from "crypto";

function verifyWebhookSecret(req: Request): boolean {
  const received = req.headers["x-documenso-secret"] as string;
  const expected = process.env.DOCUMENSO_WEBHOOK_SECRET!;

  if (!received || !expected) return false;

  // Use constant-time comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(received, "utf8"),
    Buffer.from(expected, "utf8")
  );
}

# Python equivalent
import hmac, os
from flask import request

def verify_webhook(req):
    received = req.headers.get("X-Documenso-Secret", "")
    expected = os.environ["DOCUMENSO_WEBHOOK_SECRET"]
    return hmac.compare_digest(received, expected)

Step 4: Document Access Control

// Principle of least privilege with API keys
// Personal keys: only YOUR documents
// Team keys: all documents in the team

Documenso Upgrade & Migration

Current State

!npm list @documenso/sdk-typescript 2>/dev/null || echo 'SDK not installed'

!npm list documenso-sdk-python 2>/dev/null || pip show documenso-sdk-python 2>/dev/null | head -3 || echo 'Python SDK not installed'

Overview

Guide for upgrading between Documenso API versions and SDK updates. Documenso has two API versions: v1 (legacy, document-centric) and v2 (recommended, envelope-based with multi-document support). The TypeScript and Python SDKs use the v2 API by default.

Prerequisites

• Current Documenso integration working
• Test environment available
• Feature flag system (recommended for gradual rollout)

API Version Comparison

Instructions

Step 1: Upgrade SDK to Latest

# Check current version
npm list @documenso/sdk-typescript

# Upgrade
npm install @documenso/sdk-typescript@latest

# Check for breaking changes
npm info @documenso/sdk-typescript changelog

# Python
pip install --upgrade documenso-sdk-python

Step 2: v1 REST to v2 SDK Migration

// BEFORE: v1 REST API
const BASE = "https://app.documenso.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` };

// Create document
const res = await fetch(`${BASE}/documents`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Contract" }),
});
const doc = await res.json();

// List documents
const listRes = await fetch(`${BASE}/documents?page=1&perPage=20`, { headers });
const { documents } = await listRes.json();

// AFTER: v2 SDK
import { Documenso } from "@documenso/sdk-typescript";
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

// Create document
const doc = await client.documents.createV0({ title: "Contract" });

// List documents
const { documents } = await client.documents.findV0({ page: 1, perPage: 20 });

Step 3: Gradual Migration with Feature Flags