DocuSign Integration Hub

DocuSign is the e-signature platform used for all RERI real estate transactions — purchase agreements, listing agreements, disclosures, and TC documents. The DocuSign Connect webhook delivers real-time envelope and recipient events to the OpenClaw webhook handler at :18790. Security model: dual-layer — WAF IP allowlist (Cloudflare Pro, DocuSign CIDR blocks) + HMAC-SHA256 signature verification (X-DocuSign-Signature-1 header). Read this hub before any Connect configuration change, WAF rule edit, or HMAC key rotation.

---

⚠️ WAF ALLOWLIST STALENESS WARNING (PF-A — MANDATORY READ)

security-audit-funnel.timer last fired: 2026-04-27 — that is >6 days ago. The timer is scheduled for Mondays 06:00 America/Los_Angeles. Missed multiple Monday runs. This is a G-FAILED-SERVICE-MTTR violation candidate (>24h in degraded state).

DocuSign WAF IP allowlist conceptually expires every 90 days. Last KB verification: 2026-04-20. Next mandatory review: 2026-07-20. Current WAF rule ID: b6a75b6e4fab41bba068562c4ca4ea8b.

Action required before next DocuSign webhook goes live:

1. Run manually: node workspace/scripts/security-audit-funnel.js --dry-run
2. Compare Cloudflare WAF rule against current IP list at docusign.com/trust/security/esignature
3. If new CIDRs found: update WEBHOOK-IP-RANGES → update Cloudflare WAF rule → retest
4. Staleness risk: DocuSign events silently return 403 if new IPs added and we miss them

See cloudflare for WAF management detail and Cloudflare API endpoints.

---

Quick reference

Field	Value
Vendor	DocuSign
URL	https://developers.docusign.com / https://admin.docusign.com
KB doc	API · WEBHOOKS
Auth method	OAuth 2.0 — JWT Grant (server-to-server) or Authorization Code
Auth credential	op://Aurora/docusign/integration-key · op://Aurora/docusign/rsa-private-key · op://Aurora/docusign/account-id
HMAC Connect secret	op://Aurora/docusign/connect-hmac-secret
Cred-proxy port	n/a (until B1-B6 ratified per nemoclaw-audit-2026-05-03)
Webhook port	:18790 (shared with HubSpot handler)
Webhook handler	hubspot-handler (workspace/webhooks/hubspot-handler.js)
Webhook path	/webhook/docusign
Webhook dedup table	processed_webhook_events (24h TTL) — dedup key: envelopeId + event
Tunnel path	webhook.reri.co/webhook/docusign via cloudflare
Outbound API base	https://na1.docusign.net/restapi/v2.1 (prod) · https://demo.docusign.net/restapi/v2.1 (demo)
Auth server	https://account.docusign.com (prod) · https://account-d.docusign.com (demo)
Rate limits	1,000 req/hr per account; burst 50 req/sec
Rate-limit action	429 → exponential backoff (3 retries) + Discord ops alert
Cost	Business Pro ~$45/user/mo\cdot Enhanced$65/user/mo (unlimited envelopes); API included on paid plans
Backup/recovery	DocuSign-managed; completed documents downloadable via API for 10 years
Discord alert channel	betterfiles-build (TC events) · ops (errors)
Drift cadence	weekly (security-audit-funnel.timer) — CURRENTLY STALE: last run 2026-04-27
Status	approved-inactive (Connect config not yet live — 0 active Connect configs per FUNNEL-REGISTRY)

---

Components

• workspace/webhooks/hubspot-handler.js — shared handler at :18790; DocuSign events routed via event field dispatch
• workspace/knowledge-base/docusign/API.md — envelope CRUD, recipients, templates, embedded signing, JWT auth
• workspace/knowledge-base/docusign/WEBHOOKS.md — Connect config, event types, payload schema, retry logic
• workspace/knowledge-base/security/WEBHOOK-IP-RANGES.md — DocuSign CIDR blocks (NA prod + Azure migration + GCP), STALENESS PROTOCOL
• workspace/FUNNEL-REGISTRY.md — /webhook/docusign entry: approved-inactive, WAF IP allowlist, 0 Connect configs live
• workspace/scripts/security-audit-funnel.js — weekly WAF drift detector; timer last fired 2026-04-27
• workspace/scripts/docusign-contract-draft.js — (MCP skill docusign_contract_draft) — envelope creation + template dispatch

---

How it’s used

• Trigger: TC team or Aurora dispatches a purchase agreement, CDA, or disclosure for signature via docusign_contract_draft MCP tool
• Outbound flow: Create envelope via JWT-authenticated API → DocuSign sends signing emails to recipients → signers complete via DocuSign web UI
• Inbound webhook (Connect): DocuSign POSTs envelope-completed / envelope-declined / recipient-signed events to webhook.reri.co/webhook/docusign
• Agents involved: Aurora (orchestrator — dispatches via _summary), Atlas (financial tracking), BetterFiles TC workflow
• On envelope-completed: Update HubSpot deal stage → “Docs Signed” via hubspot; notify #betterfiles-build Discord; archive signed PDF to Google Drive transaction folder
• On envelope-declined: Alert TC team via Discord DM + channel; log to HubSpot deal notes
• Custom fields: Envelopes carry transaction_id, hubspot_deal_id, property_address as textCustomFields; webhooks use these for routing
• Failure mode: WAF IP mismatch silently 403s (DocuSign marks delivery failed after 5 retry attempts); use GET /connect/failures to recover + PUT /connect/envelopes/retry to replay
• Success criteria: HTTP 200 within 100 seconds; envelopeId + event deduped in processed_webhook_events

---

Security model

Layer	Implementation	Status
WAF IP allowlist	Cloudflare Pro rule b6a75b6e4fab41bba068562c4ca4ea8b — DocuSign CIDR blocks	⚠️ staleness check overdue (last verified 2026-04-20)
HMAC signature	X-DocuSign-Signature-1 · HMAC-SHA256 · raw body · Base64-encoded	⚠️ not configured (0 Connect configs live)
HTTPS only	DocuSign will not POST to HTTP in production	enforced by tunnel
Dedup	processed_webhook_events 24h TTL on (envelopeId, event)	enforced at handler
Audit log	webhook_audit_log non-blocking write + /tmp fallback	per FUNNEL-REGISTRY governance

90-day IP rotation protocol: Visit docusign.com/trust/security/esignature quarterly → compare against WAF rule → update WEBHOOK-IP-RANGES → update Cloudflare WAF rule via API. Failure = silent 403 on all DocuSign Connect deliveries. Next review due: 2026-07-20.

---

Envelope lifecycle

Create Envelope (JWT auth) → status: "sent"
  → Recipient opens email → status: "delivered"
    → Recipient signs → recipient-status: "signed"
      → All signed → envelope-status: "completed"
        → Connect POST to /webhook/docusign
          → Handler verifies HMAC
            → HubSpot deal stage update
            → Discord #betterfiles-build notification
            → Archive PDF download

---

Cross-links

Agents that touch this

• _summary — orchestrates envelope dispatch via docusign_contract_draft MCP tool
• _summary — financial tracking; monitors signed deal documents

Skills that invoke this

• betterfiles-dispo-emails — generates and sends TC document packages
• betterfiles-cda — Commission Disbursement Allocation; delivered via DocuSign envelope

Plans that govern this

• openclaw-self-improvement-layer-2026-05-03 — OSIL B10 LiveKit + BetterFiles workflow improvements
• openclaw-fragmentation-fix-2026-05-01 — G-SERVICE-PRE-START-DOC gate applies to Connect config go-live

Feedback rules

• feedback_no_plaintext_creds — HMAC secret and RSA key must stay in 1Password, never in tracked files
• feedback_action_gate_violation_repeated — Connect config changes require Henry sign-off before activation
• feedback_blocker_surfacing — WAF staleness is a live blocker; surface in SESSION-AUDIT
• feedback_service_pre_start_doc — activating Connect requires FUNNEL-REGISTRY entry update

KB / source docs

• API — envelope CRUD, recipients, templates, JWT auth, rate limits
• WEBHOOKS — Connect config API, payload schema, retry schedule, HMAC verification
• WEBHOOK-IP-RANGES — CIDR blocks + 90-day staleness protocol (DocuSign section)

System maps

• request-lifecycle — DocuSign events enter the request lifecycle at the webhook layer
• ports-topology — :18790 shared handler (HubSpot + DocuSign)
• auth-chain-map — JWT Grant flow for outbound API calls
• external-integrations — DocuSign as external signing platform node

---

Related: Document signing + payment cluster

DocuSign and Stripe form the loose “Doc-signing + payment” cluster (Wave 2 taxonomy). Two members, no dedicated cluster hub:

• docusign — this file — e-signature for contracts and disclosures
• stripe — payment processing for deal fees and subscriptions

Both are relatively low-volume, high-criticality integrations. Neither yet has an active OpenClaw webhook handler in production (DocuSign: 0 Connect configs live; Stripe: not yet integrated).

---

Related: Webhook/tunnel cluster

DocuSign is a member of the webhook/tunnel cluster. All inbound Connect events traverse the Cloudflare tunnel:

• cloudflare — tunnel config, WAF IP allowlist rule, FUNNEL-REGISTRY governance
• hubspot — shares :18790 handler; HubSpot and DocuSign events co-processed
• openphone-quo — sibling webhook cluster member
• salesmsg — sibling webhook cluster member
• twilio — sibling webhook cluster member
• discord — notification destination for DocuSign events

---

Open issues / TODOs

• P0 BLOCKER: security-audit-funnel.timer last ran 2026-04-27 — run manually NOW before any DocuSign work: node workspace/scripts/security-audit-funnel.js --dry-run
• P0: 0 active Connect configurations live — DocuSign webhooks not flowing. Complete setup per FUNNEL-REGISTRY approved-inactive entry
• P1: Configure HMAC secret in DocuSign Connect settings → store in op://Aurora/docusign/connect-hmac-secret → implement handler verification
• P1: Add X-DocuSign-Signature-1 HMAC verification to hubspot-handler.js DocuSign route
• P2: Investigate security-audit-funnel.timer — missed multiple Monday runs. Check: systemctl --user status security-audit-funnel.timer
• P2: When Connect goes live, update FUNNEL-REGISTRY entry from approved-inactive to approved
• P3: Evaluate cred-proxy eligibility once NemoClaw B1-B6 ratified — DocuSign RSA private key is a high-value credential

Recent activity

• 2026-05-03: Hub created (Wave 2 W2-S6). WAF staleness flagged. PF-A scope-change insert applied.
• 2026-04-27: FUNNEL-REGISTRY last reviewed; DocuSign entry status: approved-inactive
• 2026-04-20: DocuSign CIDR blocks verified in security/WEBHOOK-IP-RANGES.md (next review: 2026-07-20)