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.

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 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. Edits to the Docusign template push back on the next sync.

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. The portal logs every failed webhook to Settings → Webhook failures.

Demo vs production environment — Docusign has separate demo and production environments. The portal stores which you connected. To switch, disconnect and re-connect with the other.