Docusign integration

The Contractor Codex ships with built-in e-signature for contracts. If you already have a Docusign account and prefer that workflow — for example, because your legal team is set up on Docusign or you need enterprise-grade compliance certifications — you can route any contract through Docusign instead.

Built-in signing vs Docusign — when to use each

For most service businesses, built-in is the right default. Use Docusign when:

• You already pay for Docusign and want everything in one place.
• You need a specific compliance certification Docusign offers and the built-in flow doesn't.
• Your clients expect Docusign branding for trust reasons.

Connecting your Docusign account

1. Go to Settings → Docusign.
2. Click Connect Docusign. You'll be redirected to Docusign's OAuth flow.
3. Sign in to Docusign and grant access.
4. You'll land back in the portal with your Docusign account connected.

The connection stores:

• Your Docusign refresh token (encrypted at rest)
• Your Docusign account ID + base URI (the API endpoint for your region)
• Your Docusign account name (for display)

We never see your Docusign password.

How to route a contract through Docusign

When creating a contract, the composer has a Signing provider dropdown:

• In-house (default) — uses the built-in flow.
• Docusign — routes through your connected Docusign account.

Pick Docusign and send. The contract is uploaded to Docusign, an envelope is created, and your signers get Docusign's standard signing emails (not the portal's). The portal still tracks the contract in /admin/contracts — it just delegates the signing UX.

What syncs back

Docusign Connect webhooks fire to the portal at /api/webhooks/docusign on every envelope event:

• Envelope sent
• Recipient viewed
• Recipient signed
• Envelope completed
• Envelope declined or voided

The portal updates the contract's status to match. When the envelope is completed, Docusign sends us the signed PDF and we save it to the client's Documents tab — same as a built-in contract.

Importing externally-signed envelopes

You don't have to send an envelope through the portal for it to show up here. The portal can pull in envelopes you signed directly in Docusign, outside the portal entirely.

From the Docusign tab on /admin/contracts, click Sync sent envelopes. For each envelope, the portal looks at the first signer's email and matches it (case-insensitive) to a client in this org:

• Match found. The portal creates a contract tagged as a Docusign import and, once the envelope is complete, files the signed PDF to that client's Documents tab automatically.
• No match. The envelope is skipped. Add the signer as a client first, then sync again to pull it in.

Envelopes the portal already knows about aren't duplicated. Their status is refreshed instead.

Webhook signature verification

Every Docusign Connect webhook is HMAC-SHA256 signed with a key you configure during Docusign setup (DOCUSIGN_CONNECT_HMAC_KEY). The portal verifies the signature on every event and rejects unsigned or mis-signed requests. No third party can spoof a webhook to mark your contracts as signed.

In-flight visibility

While the envelope is in flight, the portal shows you:

• Which signers have opened the envelope
• Which have signed
• Live status updates as Docusign Connect fires

Open the contract detail page at /admin/contracts/<id> to see the timeline. Click Open envelope in Docusign to jump directly to the envelope in your Docusign dashboard.

Templates

If you have Docusign templates set up in your Docusign account, the portal can pull them in. From /admin/contracts/templates, click Sync from Docusign to import your Docusign templates as portal templates. The pull is one way and the synced templates are read-only in the portal. Edit a template in Docusign, then click Sync from Docusign again to refresh the cached copy here.

Routing only some contracts through Docusign

You don't have to commit to one or the other. Pick In-house or Docusign on each contract individually. Useful for:

• Sending most contracts in-house, but routing high-value or regulated ones through Docusign.
• A/B testing the two flows with your clients.

Disconnecting Docusign

To stop using Docusign:

1. Go to Settings → Docusign.
2. Click Disconnect.

In-flight envelopes already in Docusign continue to work (the connection isn't required to receive webhooks). Future contracts default back to in-house signing.

Troubleshooting

"Docusign token expired" — The refresh token rotated. Re-connect from Settings → Docusign.

"Envelope not appearing in portal" — Check Docusign Connect is configured to point at https://<your-portal-domain>/api/webhooks/docusign. If envelopes still aren't arriving after a successful signature, contact support and we'll check the webhook delivery on our end.

Demo vs production environment — Docusign has separate demo and production environments. The portal stores which you connected. To switch, pick the other environment in the Environment selector at Settings → Docusign and save. Switching environments clears the current connection, so you'll re-connect against the environment you chose.