DocuSign Integration¶

Cruits uses the DocuSign eSignature REST API with JWT Grant (server-to-server) authentication to manage embedded signing flows for worker onboarding and placement documents.

Environment Variables¶

Dev vs prod: The defaults point to the DocuSign developer sandbox (-d suffix on hosts). Swap both DOCUSIGN_BASE_URL and DOCUSIGN_OAUTH_HOST when going to production.

Setup Steps¶

1. Create a DocuSign App¶

1. Log in to the DocuSign Developer Center (sandbox) or Admin portal (production).
2. Go to Apps and Keys → Add App and Integration Key.
3. Under Authentication, add a RSA Keypair — download the private key and store it on the server (referenced by DOCUSIGN_PRIVATE_KEY_FILE).
4. Add https://<your-domain>/api/screenings/docusign/webhook as an allowed Redirect URI (required by DocuSign even for JWT grant).
5. Note the Integration Key (client ID) and set DOCUSIGN_INTEGRATION_KEY.

2. Grant Impersonation Consent¶

The service account user must grant consent to be impersonated. Navigate to:

https://account-d.docusign.com/oauth/auth
  ?response_type=code
  &scope=signature%20impersonation
  &client_id=<DOCUSIGN_INTEGRATION_KEY>
  &redirect_uri=<your-redirect-uri>

Log in as the impersonated user and accept. This is a one-time step per environment.

3. Configure DocuSign Connect (Webhook)¶

1. In the DocuSign Admin portal → Connect → Add Configuration.
2. Set the URL to https://<your-domain>/api/screenings/docusign/webhook.
3. Under Trigger Events, enable: Envelope Sent, Envelope Delivered, Envelope Completed, Envelope Declined, Envelope Voided.
4. Under Security Settings, enable HMAC signature and copy the generated secret into DOCUSIGN_WEBHOOK_SECRET.

How It Works¶

Authentication¶

DocuSignClient generates a short-lived RS256-signed JWT assertion and exchanges it for an access token via the /oauth/token endpoint. Tokens are cached in ExternalServiceToken (DB) and reused until expiry, avoiding redundant token requests.

JWT assertion (RS256) → POST /oauth/token → access_token (1 h TTL)

Envelope Lifecycle¶

create_envelope()     →  Draft envelope (status = created, no documents)
add_documents()       →  PUT documents to draft envelope (as they arrive asynchronously)
send_envelope()       →  Transition draft → sent (triggers DocuSign email / embedded view)
create_recipient_view() → Short-lived embedded signing URL (clientUserId = worker.pk)

All envelope state is persisted in DocuSignEnvelope (integrations/models.py).

Phases¶

API Endpoints¶

Webhook Verification¶

Incoming Connect requests are verified by verify_connect_signature() in integrations/docusign/client.py. The function computes HMAC-SHA256(secret, raw_body) and compares it to the X-DocuSign-Signature-1 header value (base64-encoded). Requests that fail verification receive 401.

Document Flow Reference¶

See placement-confirmation-flow.md for the end-to-end sequence showing when envelopes are created, filled, and sent within the placement confirmation journey.

Relevant Code¶