documenso-prod-checklist

Documenso Production Checklist

Overview

Complete checklist for deploying Documenso integrations to production, covering security, reliability, monitoring, and compliance readiness.

Prerequisites

• Staging environment tested and verified
• Production API keys available
• Deployment pipeline configured (see documenso-ci-integration)
• Monitoring ready (see documenso-observability)

Production Checklist

1. Authentication & Secrets

• Production API key generated (not staging key)
• API key stored in secret manager (Vault, AWS Secrets Manager, not .env)
• Webhook secret configured and verified
• Key rotation procedure documented
• Old/unused keys revoked
• Self-hosted: secrets generated with openssl rand -hex 32
• Self-hosted: signing certificate from trusted CA mounted

2. Error Handling

• All API calls wrapped in try/catch with typed errors
• Exponential backoff for 429/5xx responses
• Circuit breaker for Documenso outages
• User-friendly error messages (no raw API errors exposed)
• Error tracking integration (Sentry, Datadog, etc.)

3. Performance

• Singleton client pattern (not creating new client per request)
• Templates used for repetitive document creation
• Bulk operations use concurrency control (p-queue)
• Background processing for non-critical operations (Bull/BullMQ)
• Document metadata cached (completed documents immutable)

4. Monitoring & Alerting

• Health check endpoint: GET /health/documenso
• API error rate alerting (> 5% for 5 minutes)
• Latency monitoring (p95 > 5s)
• Webhook delivery success rate tracking
• Structured logging with sanitized PII

5. Webhooks

• HTTPS endpoint configured (HTTP rejected by Documenso)
• Webhook secret verification using constant-time comparison
• Idempotent event processing (handle duplicates)
• Async processing (respond 200 immediately, process in background)
• Dead letter queue for failed webhook processing

6. Data & Compliance

• PII sanitized in all logs (emails, names)
• Data retention policy implemented
• GDPR access/erasure request process documented
• Signed PDFs archived to durable storage
• Self-hosted: document storage strategy defined

7. Self-Hosted Production (if applicable)

• PostgreSQL with automated backups
• HTTPS via reverse proxy (nginx, Caddy, Traefik)
• Signing certificate from trusted CA (not self-signed)
• SMTP configured and tested (emails actually deliver)
• Container runs as non-root user (UID 1001)
• Resource limits set (CPU, memory)
• Automated container restarts (restart: unless-stopped)

Pre-Deployment Verification Script

#!/bin/bash
set -euo pipefail
echo "=== Documenso Production Verification ==="

# Check API key
if [ -z "${DOCUMENSO_API_KEY:-}" ]; then
  echo "FAIL: DOCUMENSO_API_KEY not set"; exit 1
fi
echo "OK: API key configured"

# Test connection
BASE="${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v1}"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1")
[ "$STATUS" = "200" ] && echo "OK: API connection ($STATUS)" || echo "FAIL: API connection ($STATUS)"

# Test webhook endpoint
WEBHOOK_URL="${DOCUMENSO_WEBHOOK_URL:-}"
if [ -n "$WEBHOOK_URL" ]; then
  WH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$WEBHOOK_URL")
  echo "Webhook endpoint: $WH_STATUS"
fi

# Check health endpoint
HEALTH_URL="${APP_URL:-http://localhost:3000}/health/documenso"
HEALTH=$(curl -s "$HEALTH_URL" 2>/dev/null | jq -r '.status' 2>/dev/null || echo "unreachable")
echo "Health check: $HEALTH"

echo "=== Verification Complete ==="

Rollback Procedure

If issues occur after deployment:

1. Immediate: revert to previous container image / deployment
   kubectl rollout undo deployment/signing-service
   # or: vercel rollback

2. Verify rollback:
   curl -s $APP_URL/health/documenso | jq '.status'

3. Investigate:
   - Check deployment diff (what changed?)
   - Review error logs for the deployment window
   - Test the failed version in staging

4. Fix and re-deploy:
   - Fix the root cause on a feature branch
   - Test in staging
   - Deploy with monitoring active

Go-Live Day Checklist

• All checklist items above verified
• Staging smoke test passed within last 24 hours
• Team notified of deployment window
• Monitoring dashboards open during deployment
• Rollback procedure documented and accessible
• Support contact for Documenso available (Discord or email)
• First production document created and verified end-to-end

Error Handling

Alert	Condition	Response
Deploy failed	CI/CD error	Check logs, fix, retry
Health check failed	Documenso unreachable	Verify API key, check status page
Error spike post-deploy	Breaking change	Execute rollback procedure
Webhook delivery stopped	Endpoint misconfigured	Check HTTPS URL, secret, event subscriptions

Resources

• Documenso Status
• Self-Hosting Tips
• Documenso Discord

Next Steps

For version upgrades, see documenso-upgrade-migration.