Digital Signature Implementation (DocuSign + .NET)

1. Overview — what this article covers

You will learn, step-by-step, how to implement DocuSign eSignature in a .NET (ASP.NET Core) app:

key concepts and authentication options (JWT vs Authorization Code)
installing and configuring the official DocuSign C# SDK and quickstart links.
code sample to create and send an envelope (server-side)
embedded signing (recipient view) sample for in-app signing
implementing and securing DocuSign Connect (webhook) listener in ASP.NET Core, including validation.
testing, error handling, logging, and deployment considerations
best practices for security, compliance, and monitoring

I’ll include working C# snippets and notes you can drop into an ASP.NET Core project.

2. Quick background: DocuSign building blocks

Account / Integration Key — your DocuSign developer account (Demo) and the App (Integration Key) you create in the DocuSign Admin.
Envelope — a container for documents, recipients, and signing fields.
Recipient & Tabs — signer (email/name) and signing tab positions (fields).
Authentication — DocuSign supports OAuth: Authorization Code and JWT Grant; for server-to-server automated flows, JWT Grant is recommended.
Connect (Webhooks) — DocuSign’s webhook system to notify your app of envelope events (completed, declined, etc.).

3. Prerequisites

DocuSign developer account ( https://developers.docusign.com ) — use Demo (sandbox).
Integration Key (app) created in DocuSign Admin with the redirect URI (if using Auth Code) or configured for JWT.
RSA keypair (private key) generated and uploaded to your DocuSign app (for JWT flow).
.NET 6 / .NET 7+ SDK and an ASP.NET Core Web API or MVC project.
NuGet packages: DocuSign.eSign (official C# SDK).

Install the SDK

  
    dotnet add package DocuSign.eSign

4. Authentication: choose the right flow

JWT Grant (service integrations): no user interaction; server exchanges signed JWT for access token. Best for backend services that act on behalf of users or a system account. Requires consent once (admin or user).

Authorization Code Grant (user interactive): redirect user to DocuSign login page, user consents and returns code. Best for user-driven flows where the signer must authenticate with DocuSign.

Recommendation: Use JWT for server flows (creating envelopes programmatically, embedded signing server prepares envelope); use Authorization Code when the user must sign in to DocuSign itself.

5. Getting an access token (JWT) — minimal example

Upload your RSA private key to the DocuSign app (Admin → Apps and Keys).
Grant consent to your Integration Key for the impersonated user (admin consent or via browser link).

Below is a minimal JWT token flow using the DocuSign SDK helper. The SDK exposes helper classes; you can also form JWT by hand.

  
    using DocuSign.eSign.Client;
using System.Security.Cryptography;
using System.IO;

public class DocuSignAuthService
{
    private readonly string _integrationKey = "<INTEGRATION_KEY>";
    private readonly string _userId = "<IMPERSONATED_USER_ID_GUID>";
    private readonly string _authBasePath = "account-d.docusign.com"; // demo
    private readonly string _privateKeyPath = "docusign_private_key.pem"; // RSA private key (PKCS8)

    public ApiClient CreateApiClient()
    {
        var apiClient = new ApiClient($"https://{_authBasePath}");
        return apiClient;
    }

    public string GetAccessToken()
    {
        var apiClient = CreateApiClient();
        // Read private key
        var privateKey = File.ReadAllText(_privateKeyPath);
        // Requests JWT token. SDK provides a helper method.
        var oauthToken = apiClient.RequestJWTUserToken(
            _integrationKey,
            _userId,
            new List<string> { "signature", "impersonation" },
            System.Text.Encoding.UTF8.GetBytes(privateKey),
            3600);
        return oauthToken.access_token;
    }
}

Notes

Use the SDK method RequestJWTUserToken carefully (it expects private key bytes in a certain format). Refer SDK docs for exact signature.
In production, store private keys in a secure store (KeyVault, AWS KMS) — never commit to repo.

6. Create and send an envelope (server side)

This example creates an envelope with a single PDF and a single signer.

  
    using DocuSign.eSign.Api;
using DocuSign.eSign.Model;
using DocuSign.eSign.Client;
using System.Collections.Generic;

public class DocuSignService
{
    private readonly string _accountId;
    private readonly ApiClient _apiClient;

    public DocuSignService(string accessToken, string accountId, string basePath = "https://demo.docusign.net/restapi")
    {
        _apiClient = new ApiClient(basePath);
        _apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
        _accountId = accountId;
    }

    public EnvelopeSummary SendEnvelope(byte[] pdfBytes, string signerEmail, string signerName, string signerClientUserId = null)
    {
        var envelopesApi = new EnvelopesApi(_apiClient.Configuration);

        // Document
        var doc = new Document
        {
            DocumentBase64 = Convert.ToBase64String(pdfBytes),
            Name = "Sample Document",
            FileExtension = "pdf",
            DocumentId = "1"
        };

        // Signer
        var signer = new Signer
        {
            Email = signerEmail,
            Name = signerName,
            RecipientId = "1",
            RoutingOrder = "1"
        };

        // Example: add a signHere tab at absolute position
        signer.Tabs = new Tabs
        {
            SignHereTabs = new List<SignHere> {
                new SignHere { DocumentId = "1", PageNumber = "1", XPosition = "100", YPosition = "150" }
            }
        };

        var envDef = new EnvelopeDefinition
        {
            EmailSubject = "Please sign this document",
            Documents = new List<Document> { doc },
            Recipients = new Recipients { Signers = new List<Signer> { signer } },
            Status = "sent" // "sent" to send immediately, "created" to save as draft
        };

        var result = envelopesApi.CreateEnvelope(_accountId, envDef);
        return result;
    }
}

This SendEnvelope returns an EnvelopeSummary with the envelopeId you can store and track.

7. Embedded Signing (In-app signing / Recipient View)

For in-app signing (so the signer stays in your app), create a recipient view (signing URL). This requires the signer to be a embedded recipient — set clientUserId on the signer object.

  
    public string CreateRecipientView(string envelopeId, string signerEmail, string signerName, string returnUrl)
{
    var viewRequest = new RecipientViewRequest
    {
        ReturnUrl = returnUrl, // user returns here after signing
        ClientUserId = "123",  // must match Signer.clientUserId
        AuthenticationMethod = "none",
        UserName = signerName,
        Email = signerEmail
    };

    var envelopesApi = new EnvelopesApi(_apiClient.Configuration);
    var result = envelopesApi.CreateRecipientView(_accountId, envelopeId, viewRequest);
    return result.Url; // redirect user to this URL (or open in iframe if allowed)
}

Notes and security

Use clientUserId to mark recipient as embedded.
For security, generate and validate any tokens you use to let only authenticated users open the signing session.
DocuSign recommends opening the signing URL in a browser window (or iframe with proper CSP and headers) — test cross-origin policies.

8. DocuSign Connect (Webhook) — implement listener in ASP.NET Core

DocuSign Connect delivers envelope events to your public webhook endpoint. Implement a listener to receive JSON/XML notifications and verify them.

Simple controller endpoint

  
    [ApiController]
[Route("api/docusign")]
public class DocuSignController : ControllerBase
{
    [HttpPost("connect")]
    public async Task<IActionResult> Connect()
    {
        // DocuSign may send XML or JSON based on configuration
        string body;
        using (var reader = new StreamReader(Request.Body))
        {
            body = await reader.ReadToEndAsync();
        }

        // Optionally log the raw payload (ensure PII rules)
        // Validate using HMAC or OAuth method (recommended)
        // Process payload: parse envelope status, recipient events etc.

        // Respond with 200 OK quickly
        return Ok();
    }
}

Validation options (recommended):

HMAC-SHA256 validation: DocuSign can be configured to sign the payload and you validate using your shared secret.
OAuth (Connect validation) : DocuSign provides an OAuth method where they send a JWT/assertion you can validate. See DocuSign docs for recommended validation.

Example: validating HMAC

  
    public bool ValidateHmac(string requestBody, string hmacHeader, string secret)
{
    var keyBytes = Encoding.UTF8.GetBytes(secret);
    using var hmac = new HMACSHA256(keyBytes);
    var computed = hmac.ComputeHash(Encoding.UTF8.GetBytes(requestBody));
    var computedBase64 = Convert.ToBase64String(computed);
    return string.Equals(computedBase64, hmacHeader, StringComparison.InvariantCulture);
}

Configure DocuSign Admin for Connect to include your HMAC key, and check the header (DocuSign sends it in X-DocuSign-Signature or similar; check current header name in the docs).

9. Processing webhook events — idempotency & state transitions

Idempotency : Webhooks may be retried — make processing idempotent by tracking eventId or envelopeId+eventTimestamp.
Event types : sent , delivered , completed , declined , voided — handle only the ones you care about.
Security : Validate sender before processing (HMAC/OAuth).
Queue background work : Return 200 OK quickly; enqueue heavy work (DB updates, notifications) to background processors (Hangfire, Azure Functions, background queue).

10. Local testing with DocuSign Demo & ngrok

Use the DocuSign Demo account ( account-d.docusign.com ) for development.
For webhook testing, use ngrok to expose your local endpoint and register it in DocuSign Connect settings or in your app’s Connect config.

Example with ngrok

  
    ngrok http 5000
# Use the generated https URL in DocuSign Connect settings

Set the Connect listener to POST to https://<your-ngrok-id>.ngrok.io/api/docusign/connect .

11. Error handling, retries, and monitoring

Retry logic : DocuSign retries webhooks on non-2xx responses. Make sure your endpoint responds 200 quickly for accepted payloads.
Logging : Log envelopeId, event, timestamp, signer info (avoid logging sensitive fields). Use structured logging (Serilog) and centralize logs (ELK, Seq).
Metrics : Monitor envelope creation rates, webhook failures, token expiry errors.
Alerts : Alert on repeated webhook delivery failures or auth token rejection rates.

12. Example: End-to-end flow (step diagram)

  
    Developer / System
   └─> Create Envelope (server) --> DocuSign eSignature API (Create Envelope)
         └─> DocuSign sends email to recipient (if remote) OR
         └─> Server requests Recipient View URL (embedded signing) and returns URL to client

User (if embedded) visits signing URL -> signs -> DocuSign updates envelope status

DocuSign Connect (webhook) --> Your webhook endpoint (/api/docusign/connect)
   └─> You validate (HMAC / OAuth) --> enqueue processing (update DB, send notifications)

13. Deployment & CI/CD tips

Keep your DocuSign environment variables (Integration Key, AccountId, UserId, Private Key reference, base URL) in secure pipeline secrets (GitHub Actions secrets, Azure Key Vault).
If you use JWT, ensure the private key is stored in Key Vault and injected into the build/runtime securely.
Automate tests using DocuSign Demo environment (create test envelopes and assert status transitions).
Post-deploy step: validate integration by creating a test envelope and checking the Connect webhook roundtrip.

14. Security & compliance recommendations

Use HTTPS for all endpoints.
Store private keys securely (Azure KeyVault, AWS KMS).
Use JWT with short lifetimes and refresh tokens only as needed.
Mask or avoid storing PII in logs; use tokenization for sensitive values.
Audit trails : record which app/user created/modified envelopes (DocuSign records audit data; also replicate key events to your logs for compliance).
Consent and legal : ensure proper consent for e-signature use in your jurisdiction; DocuSign provides guidance for legal enforceability.

15. Testing & QA checklist

Create envelopes with different document types (PDF, DOCX) and verify field placement.
Test embedded signing flows across browsers and mobile.
Test webhook delivery and validation (use invalid signature to confirm rejection).
Simulate retries by forcing 5xx from your endpoint to ensure idempotent handling.
Validate token refresh and error handling when access token expires.

16. Useful DocuSign resources (official)

DocuSign eSignature C# SDK docs and setup.
How to get an access token with JWT Grant (official guide).
DocuSign Connect (webhooks) implementation details and security.
Official GitHub C# client repo & code examples.

(These five references are the most load-bearing sources for setup, auth, SDK, and webhook guidance.)

17. Common pitfalls and how to avoid them

Private key format mismatch : SDK expects PKCS8/PEM in certain formats — use the SDK examples or convert keys with openssl .
Missing user consent for JWT : you must obtain consent for the impersonation user once. Use the consent URL provided by DocuSign or have an admin grant consent.
Webhook not reachable (ngrok vs production) : use stable endpoints in production and avoid relying on tunneling for long-term operation.
Incorrect envelope status handling : treat "completed" as verified final state; be careful with "delivered" vs "completed".
Testing in production : don’t mix demo and production credentials.

18. Advanced topics (next steps)

Templates : Create reusable templates in DocuSign and create envelopes from templates to simplify repeated documents.
Bulk sending : Use bulk send for high-volume signature workflows.
PowerForms : Use PowerForms for self-service signature forms.
Hybrid approach : Use Authorization Code for user-initiated flows and JWT for system automation.
Connect & storage : Replace heavy webhook processing with serverless functions if you want autoscaling and pay-per-use.

19. Example repository & samples

DocuSign maintains sample repos and quickstarts (C# examples) to help you start quickly — the official GitHub repo and Developer Center have ready examples you can clone and run.

20. Summary — practical checklist before go-live

Developer account with Integration Key and correct redirect/consent configured.
Private key stored securely and not in source control.
Access tokens and refresh strategy implemented (JWT for server).
Envelope creation + recipient view flows working end-to-end.
Webhook listener implemented, validated (HMAC/OAuth), and idempotent.
Logging, monitoring, and alerts in place for failures and retries.
QA: cross-browser signing, mobile signing, retry behavior tested.
Legal/compliance: retention, consent, and audit trail verified.