Building a Robust E-Signature Workflow: Lessons from an HRMS Implementation.

Gaurav Rathore — Thu, 02 Apr 2026 09:30:57 +0000

If your product handles offer letters, contracts, onboarding forms, NDAs, or approval workflows, document signing eventually becomes a core feature, not just a nice-to-have.

I recently implemented e-sign documents in an HRMS platform using DocuSeal, with both frontend and backend support. The goal was simple: users should be able to open a document inside the app, sign it, and let the system automatically store the final signed copy and audit log.

This post breaks down the architecture I used and turns it into a** reusable implementation pattern** you can apply in almost any project.

Why DocuSeal worked well for this use case

When adding document signing to a product, I needed a setup that could support:

Template-based signing
Multiple signers
Embedded signing inside the app
Prefilled user data
Webhook/callback support
Final signed document retrieval

DocuSeal fits this flow well. It lets you create templates, generate submissions, embed the signing UI, and receive completion callbacks.

That means your app can own the business logic and workflow state, while DocuSeal handles the actual signing experience.

The architecture at a glance

A clean document-signing flow usually looks like this:

Upload a document and create a DocuSeal template
Define signer roles and fields
Create a submission for a specific user
Prefill known values like name, email, and address
Open the embedded signing UI in the frontend
Receive a callback when signing is completed
Download the signed files and audit log
Store everything in your own system

Here’s the same flow in a simple developer-friendly view:

Frontend -> requests signing URL / slug from Backend Backend -> authenticates user -> fetches DocuSeal submission details -> returns signer slug Frontend -> mounts DocuSeal -> sends callback/webhook on completion Backend -> verifies callback secret -> queues event processing -> downloads signed PDF + audit log -> stores files -> updates signer/package status in DB

1. Keep DocuSeal behind your backend

A critical architectural decision is keeping the DocuSeal API behind your backend.

Why this matters:

your API key stays private
you control submission creation
you can validate permissions before exposing a signing session
you can map DocuSeal IDs to your own internal records

In my project, the backend used environment-based configuration like:

DOCUSEAL_API_KEY
DOCUSEAL_ADMIN_EMAIL
DOCUSEAL_BASE_URL
DOCUSEAL_CALLBACK_EVENT_SECRET_KEY
DOCUSEAL_CALLBACK_EVENT_SECRET_VALUE

This pattern is much safer than letting the frontend talk directly to DocuSeal.

2. Create templates from uploaded files

The first backend capability you need is template creation.
In my implementation, the backend:

reads the uploaded file
sends it to DocuSeal
uses /templates/pdf for PDFs
uses /templates/docx for DOCX files

This makes any uploaded contract, policy, or agreement reusable as a signing template.

Best practice: treat templates as reusable infrastructure, not one-off documents.

3. Use a template builder for field placement

On the frontend, I used @docuseal/react and embedded the DocusealBuilder component.

That allowed admins to:

open a template
define signer roles
place fields like text, date, phone, checkbox, and signature
save the field metadata back into our own system

This is an important design choice. Document signing is not just “upload and sign.” You also need to know:

which field belongs to which signer
which fields are prefilled
how those fields map back to your own domain model

4. Create submissions dynamically

Once the template exists, the next step is creating a submission.
In HRMS, a submission is created when a user needs to sign a document package. The backend sends DocuSeal:

template_id
signer list
signing order
delivery preferences
prefilled field values

For each signer, I passed values like:

name
email
phone
external_id
role
fields

The external_id is especially useful because it links the DocuSeal signer back to your own user record.

That one field makes later syncing dramatically easier.

5. Prefill known user data

This is one of the biggest UX wins in any signing flow.

Instead of asking users to manually type information your app already knows, I prefilled values such as:

first name
last name
email
phone
city
province
postal code
street address

A simplified example looks like this:

{ name: "first_name", readonly: true, default_value: user.firstName }

This keeps the signing flow focused on review and approval, not repetitive data entry.

Practical tip: ensure your template field names match either your database keys directly or a clean mapping object.
For example, fields like employee_city, employee_email, or postal_code should map predictably, otherwise the prefill logic becomes messy very quickly.

6. Embed the signer directly in your app

For the signing experience, I used DocusealForm from @docuseal/react.

The frontend fetches the signer slug from the backend, then mounts the signing form inside a modal/dialog:

<DocusealForm src={`https://docuseal.com/s/${submitter.slug}`} email={submitter.email} onComplete={handleComplete} />

This makes the flow feel native to your product, instead of bouncing users to a disconnected external page.

That small UX detail makes a big difference in onboarding and HR workflows.

7. Webhook verification is non-negotiable

This is one area where backend discipline matters.

The frontend onComplete callback is useful for updating the UI, but it should not be your source of truth. The real source of truth should be the backend callback/webhook from DocuSeal.

In my implementation, the backend validates a shared secret header before processing the callback. That ensures the request is actually coming from the signing provider.

At minimum, verify a shared secret header.
If your signing provider supports HMAC-signed webhook verification, that adds an even stronger layer of protection.

Either way, callback verification is not optional.

8. Process callbacks asynchronously

Another important decision was to avoid doing all the heavy work directly inside the callback request.

Instead, the system:

accepts the callback
pushes it into a queue
processes the event in the background
updates signer state
fetches final submission details
downloads signed files
stores the audit log

This pattern is much more reliable, especially when:

documents are large
multiple signers complete at the same time
storage uploads take time
external API calls are slow

*Queues turn webhook handling from fragile to production-ready.
*

9. Download and store signed files yourself

Once a submission is completed, the backend fetches the final DocuSeal submission and downloads:

the signed documents
the audit log PDF

Then those files are uploaded into the application’s own storage layer and attached to internal records.

This is a very important design principle:

*DocuSeal should power the signing workflow, but your application should own the final business record.
*
That makes it easier to:

show signed files later
attach documents to employee records
support audits and compliance
reduce long-term coupling to the provider

10. Track signer state in your own database

In addition to DocuSeal’s status, I also stored signer state in our own database:

pending
signed
declined

That allowed the product to answer workflow questions such as:

which package is still waiting for signature?
which signer has completed?
should the signing button still be shown?
is onboarding ready to move to the next step?

This is the key mindset:
DocuSeal is the signing engine. Your database is the workflow engine.

Practical lessons

Use external_id everywhere. It is the cleanest way to connect DocuSeal events back to your own users.
Prefill aggressively. If your system already knows the data, don’t ask the user to type it again.
Do not trust only the frontend completion event. UI callbacks are for UX; backend callbacks are for correctness.
Store final signed documents in your own system. Do not make the provider your only source of truth.
Separate template management from submission generation. Templates are reusable assets; submissions are workflow instances.

A reusable implementation pattern

If I had to summarise the best implementation pattern for any project, it would be this:

Use DocuSeal for template creation and embedded signing
Keep all provider communication in the backend
Store template metadata in your own DB
Create submissions per workflow or transaction
Prefill signer fields from your own user data
Embed the signer inside your frontend
Verify callbacks before processing them
Use a queue for callback handling
Download and store signed files yourself
Track signer status in your own database

This pattern works well not only for HRMS, but also for:

hiring platforms
CRMs
vendor onboarding systems
finance workflows
legal tools
procurement platforms
internal approval systems

Final thoughts

Document signing often looks like a small feature at first, but in practice it touches templates, users, storage, security, callbacks, workflow state, and permissions.

What worked especially well for me was treating DocuSeal as the signing layer, while keeping the actual product logic inside my own backend and frontend.

That gave me the best of both worlds:

a fast signing integration
full control over the user experience
reliable backend processing
ownership of the final signed records

If you’re planning to add document signing to your product, this architecture is a strong place to start.

DEV Community: Gaurav Rathore