Skip to main content

Migrating Data from DocuSign

Automatically sync and import envelopes (DocuSign's term for signing requests) from DocuSign into Propper Sign using DocuSign Connect webhooks. This allows you to maintain a complete record of all your signed documents in one place during and after migration.

Executive Summary

What: Keep your DocuSign documents synced to Propper during (and after) migration.

How it works: DocuSign sends automatic notifications to Propper whenever a document is signed, declined, or voided. Propper receives these notifications and imports the documents.

Why use this: You get a complete record of all signatures in Propper without manual effort, and existing DocuSign workflows continue working during your transition.

Related Guides

What This Integration Does​

DocuSign Connect sends real-time notifications (webhooks) to Propper whenever something happens to a signing request. Propper uses these notifications to:

CapabilityWhat It Means
Sync agreement statusAutomatically update status as documents move through the signing process (sent → delivered → completed / declined / voided)
Import signed documentsStore final signed PDFs and audit certificates in Propper—no manual downloads needed
Track recipient progressSee when each signer receives, views, signs, or declines the document
Maintain audit trailKeep a complete log of all events for compliance and troubleshooting
Important: Delivery vs Processing

Webhook delivery "success" (HTTP 200) means Propper received the event, not necessarily that document import succeeded. Always check the webhook logs for actual processing status. See Monitoring & Retries below.

Prerequisites​

Before setting up DocuSign Connect, you'll need:

  1. DocuSign Admin access - Administrator privileges in your DocuSign account
  2. Propper Sign access - Sign admin permissions in your Propper organization
  3. DocuSign Connect feature - Must be enabled for your DocuSign account (availability depends on your plan)

Quick Start​

Step 1: Enable DocuSign Connect in Propper​

  1. Navigate to Organization → DocuSign Connect in Propper
  2. Copy your unique webhook URL (displayed on the settings page)
  3. Choose security method:
    • HMAC (recommended), or
    • Basic Auth (fallback)
  4. Enable Auto-Import (recommended for migrations)
  5. Click Save Configuration

Step 2: Configure DocuSign Connect​

  1. In DocuSign Admin ↗: Integrations → Connect
  2. Click Add Configuration → Custom
  3. Paste the Propper webhook URL
  4. Select JSON SIM format (DocuSign's modern JSON format - required, not legacy XML)
  5. Select events (see Recommended Configuration below)
  6. Configure security (HMAC or Basic Auth)
  7. Enable:
    • ✅ Require Acknowledgement
    • ✅ Log failures with Connect

Step 3: Test​

  1. Send a test envelope in DocuSign (use sandbox if available)
  2. Complete the signing process
  3. In Propper: Organization → DocuSign Connect → Recent Activity
  4. Confirm:
    • Event received with "Completed" status
    • Agreement created with document attached (if Auto-Import enabled)

Event Selection​

Envelope events (agreement-level status):

EventPurposeRequired?
Envelope SentTrack when envelopes are sent for signatureRecommended
Envelope DeliveredKnow when all recipients have received the envelopeRecommended
Envelope CompletedImport completed/signed documentsRequired
Envelope DeclinedTrack declined envelopesRecommended
Envelope VoidedTrack cancelled envelopesRecommended

Recipient events (signer-level visibility):

EventPurpose
Recipient DeliveredTrack when each signer receives the envelope
Recipient CompletedTrack when each signer completes signing
Recipient DeclinedTrack when a specific signer declines
Minimal Setup

If you only want to import final signed PDFs, start with Envelope Completed only and expand later.

Data Options (Minimize Payload Size)​

OptionRecommendationNotes
Include Recipients✅ RecommendedRequired for recipient status tracking
Include Certificate of Completion✅ RecommendedStores DocuSign's audit certificate in Propper
Include Documents⚠️ Use carefullyRequired for PDF import, but significantly increases payload size
Best Practice: Documents Only on Completed

Including documents makes payloads huge (Base64-encoded PDFs). For production:

  • Send status-only events for Sent/Delivered/Declined/Voided
  • Send documents only for Completed events

This reduces payload size, latency, and failure rate. Configure this in DocuSign Connect's event notification settings.

Security Configuration​

DocuSign signs webhook payloads using an HMAC key you generate in Connect. Propper verifies that signature before processing.

Setup:

  1. In DocuSign Connect: scroll to HMAC Authentication
  2. Click Generate Secret Key (this is your "Connect Key")
  3. Copy the generated key
  4. Paste into Propper's HMAC Secret field
  5. Save both configurations

Validation Gotchas (Common Failures):

IssueSolution
Secret mismatchEnsure exact match - no extra whitespace
Wrong validation methodValidate against raw request body bytes (before JSON parsing)
Header casingUse exact header: X-DocuSign-Signature-1
Multiple signaturesDocuSign may send multiple signature headers - validate against at least one
Technical Detail

DocuSign uses HMAC-SHA256. The signature is computed over the exact raw bytes of the request body, not the parsed JSON. Ensure your validation doesn't modify the body before verification.

Option B: Basic Authentication (Fallback)​

Use if HMAC is not available in your DocuSign plan:

  1. In Propper: enable Require Basic Authentication and set credentials
  2. In DocuSign Connect: scroll to Require Mutual TLS (mTLS) or Basic Authentication
  3. Check Require Basic Authentication
  4. Enter the same username and password

How Propper Processes Events​

Processing Flow​

DocuSign → Propper Webhook → Verify Auth → Log Event → Queue Processing → Update/Import
  1. Receive - Webhook arrives at your organization's endpoint
  2. Verify - HMAC signature and/or Basic Auth credentials verified
  3. Log - Event recorded in webhook logs (always, even if processing fails later)
  4. Queue - Event queued for async processing
  5. Process - Agreement status updated and/or documents imported
  6. Complete - Processing status updated in logs

Delivery vs Processing​

Understanding the difference is critical for troubleshooting:

TermMeaning
Delivery Success (HTTP 200)Propper received and accepted the webhook for processing
Processing SuccessAgreement was updated and/or documents were imported

Propper returns HTTP 200 once the event is accepted (logged and queued), even if downstream processing fails. This follows DocuSign's recommended async pattern ↗ and prevents duplicate deliveries.

If processing fails:

  • Check the webhook log entry for error details
  • Use Propper's retry mechanism (coming soon) or contact support
  • DocuSign will NOT automatically retry since we returned 200

Envelope Status Mapping​

Agreement status in Propper follows DocuSign envelope status (not recipient status):

DocuSign Envelope StatusPropper Agreement Status
createdCREATED
sentSENT
deliveredDELIVERED
completedCOMPLETED
declinedDECLINED
voidedVOIDED

Recipient Status (Signer Progress)​

Recipient events track individual signer progress and are stored separately from the agreement status:

DocuSign Recipient EventWhat It Means
recipient-sentEnvelope sent to this recipient
recipient-deliveredRecipient received/opened the envelope
recipient-completedRecipient finished all required actions
recipient-declinedRecipient declined to sign
Status Source of Truth

The agreement status in Propper always reflects the envelope status from DocuSign. Recipient events provide granular signer-level visibility but don't directly change the agreement's final status.

Monitoring and Troubleshooting​

View Webhook Activity

Open DocuSign Connect Dashboard →

See all incoming webhooks, their processing status, and detailed payloads in real-time.

Viewing Webhook Logs​

From the DocuSign Connect dashboard:

  1. Scroll to Recent Activity
  2. Click any row to view full details including the raw payload

Each log entry shows:

FieldDescription
Envelope IDDocuSign envelope identifier
Event TypeWhat triggered the webhook
StatusProcessing result (Completed, Failed, Rejected)
HMAC VerifiedWhether signature verification passed
Agreement IDLinked Propper agreement (if matched/created)
Received AtWhen the webhook arrived

DocuSign Retry Behavior​

With Require Acknowledgement enabled, DocuSign:

  • Waits up to ~100 seconds for HTTP 200 before treating delivery as failed
  • Uses exponential backoff for retries when delivery fails
  • Logs all delivery attempts in DocuSign Admin → Connect → Logs

Common Issues​

Webhooks Not Arriving​

CheckAction
Connect statusEnsure configuration is Active in DocuSign Admin ↗
URL matchVerify URL in DocuSign matches the one shown on your DocuSign Connect settings page
DocuSign logsView delivery attempts in DocuSign Admin → Connect → Logs
Response timeEnsure your endpoint responds within 100 seconds (timeouts are common with large payloads)

HMAC Verification Failing​

CheckAction
Secret mismatchCopy/paste fresh - check for whitespace
Validation methodMust validate raw bytes, not parsed JSON
Header nameUse X-DocuSign-Signature-1 (case-sensitive)

Documents Not Importing​

CheckAction
Include DocumentsMust be enabled in DocuSign Connect
Auto-ImportMust be enabled in Propper settings
Payload timeoutLarge documents may cause timeouts - consider "documents only on completed"
Storage quotaCheck organization has available storage

Status Not Updating​

CheckAction
Event selectionEnsure relevant envelope events are selected
Agreement existsFor updates, the agreement must already exist in Propper
Envelope IDMust match between DocuSign and Propper

Importing Historical Envelopes​

After setting up DocuSign Connect for real-time sync, import your existing completed envelopes using DocuSign's publish features.

Option 1: Admin UI Publish (Simple)​

Best for: Small to medium volumes, one-time imports

  1. Go to apps.docusign.com/admin/envelopes/publish ↗
  2. Select your Propper Connect configuration
  3. Set date range and filter by status (e.g., Completed only)
  4. Click Select All then Publish

Option 2: API Publish (Large Migrations)​

Best for: Large volumes, automated/scheduled imports

DocuSign provides Envelope Publish API endpoints ↗ for programmatic bulk publishing.

Rate Limits:

  • Historical publish transactions: ~9,999 envelopes/hour
  • Batch by date range to stay within limits
  • Run during off-peak hours

Resources:

Best Practices for Bulk Import​

PracticeWhy
Test with small batch firstVerify setup with 5-10 envelopes before full import
Monitor webhook logsWatch for failed or rejected events
Batch by date rangeStay within rate limits, easier to track progress
Import during off-peak hoursReduce impact on production traffic
Verify sample agreementsSpot-check imported documents in Propper Sign

Migration Playbook​

Follow these phases for a complete migration from DocuSign to Propper:

Phase 1: Setup​

  • Configure DocuSign Connect in Propper
  • Create Connect configuration in DocuSign
  • Configure HMAC security
  • Test with a single envelope

Phase 2: Historical Import​

  • Plan import batches by date range
  • Import historical completed envelopes
  • Monitor webhook logs for failures
  • Retry any failed imports

Phase 3: Verification​

  • Sample 5-10% of imported agreements
  • Verify documents are attached correctly
  • Confirm status mapping is accurate

Phase 4: Cutover​

  • Begin creating new agreements in Propper Sign
  • Keep DocuSign Connect active for any remaining DocuSign envelopes
  • Monitor both systems during transition period

API Reference​

Webhook Endpoint​

Your organization's unique webhook URL is displayed on the DocuSign Connect settings page.

Headers:

HeaderDescription
X-DocuSign-Signature-1HMAC-SHA256 signature (if configured)
AuthorizationBasic auth credentials (if configured)
Content-Typeapplication/json

Response:

{
  "received": true,
  "requestId": "uuid",
  "success": true,
  "logId": "uuid",
  "agreementId": "uuid",
  "isNewImport": true
}
FieldDescription
receivedAlways true if webhook was accepted
successWhether initial processing succeeded
logIdID of the webhook log entry (use to check processing status)
agreementIdID of created/updated agreement (if applicable)
isNewImporttrue if a new agreement was created

Next Steps​

Propper Documentation​

DocuSign Documentation ↗​