documenso-prod-checklist

Instructions

1. Complete evidence gates for workspace/identity, template/version review, signer authorization, data/retention, callbacks, audit, monitoring, and rollback.
2. Validate the exact production role/audience and signing lifecycle with approved safe checks.
3. Stop production enablement when any document, identity, security, or owner gate is unverified.
4. Record the named go/no-go decision and post-release observation result.

Output

• A production-readiness receipt with owners, evidence links, approved exceptions, and tested rollback path.

Examples

Validate a new template in staging with synthetic signers, verify the production access roles and callback endpoint under review, then release to an approved canary. If authorization, state, or audit behavior differs, halt the release and restore the prior approved template.

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.