A signature shows that a person agreed to something. It shows much less about whether that something was the document your business approved. In many integrations, legal or finance approves a contract at one moment, a template or data source changes at another, and a worker sends the request later. Most teams only discover the gap when a counterparty or auditor asks, "Is this the version we approved?"
This article is for backend engineers, solution architects, and platform leads who send documents through an eSignature API. It covers a narrow problem: how to bind the content a person approved to the content a signer actually receives and signs. It does not cover whether the signature itself is legally valid. Other articles on this site cover that, including the guide to legally defensible audit trails.
The design below is a proposed design. It is not a proprietary method eSignly already operates, and it is not an API feature. It is a pattern you can build on your side of the integration, using your own database and any REST eSignature API. The code is illustrative. Confirm endpoint names, fields, and event semantics against the official API documentation before you implement anything.
- Where approved and signed content drift apart, and who usually owns each drift point
- A ledger design built on hashes, pinned template references, and atomic send claims
- How to handle ambiguous timeouts, webhook acknowledgment, and completion checks without guessing
- A comparison of three binding strategies and a set of all-required go/no-go controls
Key Takeaways
- Bottom line: Record approval against a content hash, not against a deal or ticket. Any change to the content creates a new hash and needs a new approval.
- Name the gap: In this article's proposed model, the approval-to-signature gap is the time and the set of systems between "someone approved this content" and "a signer saw this content." Control that gap on purpose.
- Prefer exact bytes: Where the use case allows it, send the exact approved file. Use provider-side templates with merge fields only when you can pin them or detect drift afterward.
- Send once, or reconcile: Bind a tenant-scoped operation identity to the approved hash. Claim work atomically. After an ambiguous timeout, check authoritative state before any retry.
- Unknown is not success: If you cannot confirm that the signed document matches the approved one, record that as unverifiable. Do not trigger downstream actions as though it were verified.
- Hashes help with integrity only: They do not prove signer identity, intent, or legal enforceability. Those need separate controls and legal review.
Why the Approved Document and the Signed Document Drift Apart
Key point: Drift rarely comes from an attack. It comes from ordinary systems changing between approval and send, with nobody owning the whole path.
A contract usually travels through a pipeline: draft, internal approval, rendering or merge, send, sign, archive. Each stage is often owned by a different team and stored in a different system. Approval happens in a workflow tool or a ticket. Rendering happens in a template engine or in the eSignature platform's template feature. Sending happens in a background worker. The approval record usually points at a business object, such as a deal, a quote, or an employee record, rather than at specific content.
Security engineers will recognize this pattern as a time-of-check to time-of-use problem. You check something at one moment and rely on that check at a later moment, and the thing can change in between. The general weakness class is described in CWE-367 on time-of-check time-of-use race conditions. In document workflows the "resource" is the content of the agreement, and the gap is often hours or days long.
Where drift enters
| Drift point | What changes | Typical owner | How it shows up |
|---|---|---|---|
| Template edited after approval | Clause text, field layout, default values | Sales ops, legal ops | Signer sees newer wording than the approver saw |
| Merge data refreshed before send | Prices, dates, addresses, names | CRM or ERP owner | Numbers on the signed document differ from the approved quote |
| Retry re-renders the document | Any of the above, at a later time | Integration team | Two different documents reach the same signer |
| Signer set or role mapping changes | Who receives and signs | Business owner | Wrong person, or wrong order, relative to the approved plan |
| Archive step re-encodes or re-saves | File bytes, metadata | Platform or records team | Archived copy cannot be matched to the signed copy |
Notice that none of these rows requires a bug in the eSignature provider. Each is a governance gap in the surrounding system. That is why the control has to live in your integration, with the provider's evidence as a supporting layer.
How Most Teams Handle It, and Why That Fails
Key point: Common safeguards prove that something was approved and that something was signed. They do not prove it was the same something.
Teams generally rely on four assumptions. Each is reasonable on its face, which is why the gap survives code review.
| Common practice | What it actually establishes | What it leaves open |
|---|---|---|
| "Approved" flag on the deal or ticket | Someone approved a business object at some time | Which content version, and whether it changed afterward |
| Pin a template ID in config | The same template identifier is referenced on every send | Whether the template's content changed under that identifier |
| Keep the API request log | The request that your code attempted | What the signer saw, and whether the log contains PII you now must govern |
| Rely on the provider's audit trail | Signing events, timestamps, and signer actions on the provider side | Your internal approval, which the provider never sees |
Why smart teams still land here
Each team does its own job correctly. Legal approves what it is shown. The integration team sends what it is told to send. The provider records what happens on its platform. The missing piece is a shared, machine-checkable statement of exactly what was approved. Without it, "approved" is a human belief rather than a verifiable fact.
There is also a cost bias. Binding approval to content takes design effort up front, and the failure it prevents is rare and quiet. A mismatch usually surfaces months later, in a dispute, an audit, or a customer complaint, when it is expensive to reconstruct.
The provider's own evidence is still valuable. A certificate of completion or audit trail documents the signing ceremony, as discussed in the article on the anatomy of a technically robust audit trail. Your binding record complements it by linking that ceremony back to your approval decision.
Why This Fails in the Real World
Key point: These scenarios are illustrative composites of patterns common in integrations, not customer results. Each one is a system or governance gap, not an individual mistake.
Failure pattern 1: the template edit nobody connected to approvals
Illustrative scenario: legal approves a services agreement in the morning. In the afternoon, a sales operations administrator updates the shared template to fix a typo and, in the same edit, changes a payment-terms default. The integration keeps sending from the same template identifier. Nothing errors. Everyone involved acted reasonably: the administrator owns the template, and the integration owns the send.
Why it happened: approval was recorded against the deal, not against the content, and the template had an owner who was not part of the approval chain. See the operations leader's framework for template governance for the organizational side of this problem.
Failure pattern 2: the retry that rebuilt the document
Illustrative scenario: a worker calls the create-request endpoint, and the call times out. The retry logic runs two hours later, re-reads the customer's address from the CRM (which was updated in the meantime), re-renders the document, and calls the endpoint again. The first call had actually succeeded. The signer now holds two requests with different addresses.
Why it happened: the retry treated an ambiguous timeout as a failure and rebuilt the payload instead of reconciling the authoritative state. The reconcile-first recovery design for timeouts covers this class of failure in detail.
Failure pattern 3: completion treated as proof of content
Illustrative scenario: a webhook reports that the request is completed, and the handler provisions an account and issues an invoice. Nobody checks whether the signed document matches the approved version. A later review finds a mismatch, and by then the downstream actions have already run.
Why it happened: "completed" was read as "completed as approved." Those are different statements. The completion handoff guide explains how to gate downstream actions on verified state.
Early detection signals
- Template edits happen without a ticket that references open signing requests.
- Retries or replays rebuild payloads from live data instead of stored, approved data.
- No stored hash or immutable copy exists for the content that was sent.
- Two requests exist for the same business object and signer, with no record of which supersedes which.
- Completion handlers have no code path for "cannot confirm the content."
A Proposed Design: The Approved-Content Binding Ledger
Key point: Define a signing packet, hash it, record approval against the hash, and let nothing leave your system unless the hash still matches.
This is a proposed design for your own database. It does not depend on any eSignly-specific feature, and it should not be read as a description of how any vendor's platform works internally.
Step 1: define the signing packet
| Packet field | Purpose | Storage guidance |
|---|---|---|
| Tenant ID and business object ID | Scope every record to its tenant and its source object | Internal opaque identifiers |
| Document hash | Identifies the exact rendered file approved | Hash only. Keep the file in controlled storage with its own retention rules |
| Merge-data hash | Identifies the structured values used to fill a template | Keyed hash, because low-entropy values can be guessed back |
| Template reference | Template identifier plus any version marker you can capture | Record what the provider exposes, and note what it does not |
| Signer-set hash | Who signs, in which role and order | Keyed hash, since emails are personal data |
| Approval record | Approver ID, time, and the meaning of the approval | Immutable, append-only |
| Packet hash | One value that covers all of the above | The identity that approvals, operations, and verification reference |
Step 2: hash with the right tool for each input
- Files: Hash the exact bytes with SHA-256, one of the approved functions in NIST FIPS 180-4, the Secure Hash Standard. Do not hash a re-serialized or re-saved copy.
- Structured data: JSON can serialize in many equivalent ways, so canonicalize it first. RFC 8785, the JSON Canonicalization Scheme, gives a deterministic form. It applies to JSON only. It says nothing about PDFs or other formats.
- Low-entropy or personal values: A plain hash of an email address or a short value can be recovered by guessing candidates. Use a keyed hash (HMAC) with a per-tenant secret so a leaked ledger does not become a lookup table.
Remember that identifiers can themselves be sensitive. Provider request IDs, signer emails, and even hashes that can be linked to a person belong in your data inventory. Assign each field an owner and a retention rule. The retention and erasure ledger design is a good companion for that work.
Illustrative packet construction
function buildSigningPacket(input) { // Illustrative only. Not an official eSignly SDK or API contract. const docHash = sha256(input.renderedBytes); const dataHash = hmacSha256(tenantKey(input.tenantId), canonicalizeJcs(input.mergeData)); const signerHash = hmacSha256(tenantKey(input.tenantId), canonicalizeJcs(sortSigners(input.signers))); const packetHash = sha256(canonicalizeJcs({ tenantId: input.tenantId, objectId: input.businessObjectId, docHash: docHash, dataHash: dataHash, templateRef: input.templateRef, signerHash: signerHash, approvalMeaning: input.approvalMeaning })); return { docHash, dataHash, signerHash, packetHash }; }Approval is then recorded against packetHash. If anything in the packet changes, the hash changes, and the old approval no longer applies. That single property closes the template-edit and retry-rebuild scenarios described earlier, provided the send path enforces it.
Send, Retry, and Completion: Keeping the Binding Intact Under Failure
Key point: The binding only holds if the send path claims work atomically, treats ambiguous outcomes as unknown, and acknowledges webhooks only after durable recording.
Operation identity and atomic claim
Give every send intent a durable, tenant-scoped operation key and bind it to the approved packet hash. Reusing the key with a different hash must be rejected, not silently accepted. A legitimately later operation, such as a corrected re-send, needs a new key and an explicit link to the operation it supersedes. The supersession design for voiding and re-sending covers that relationship.
-- Illustrative PostgreSQL-style schema and statements. CREATE TABLE signing_operation ( tenant_id uuid NOT NULL, operation_key text NOT NULL, packet_hash text NOT NULL, state text NOT NULL, claimed_by text, claim_expires timestamptz, provider_ref text, supersedes_key text, PRIMARY KEY (tenant_id, operation_key) ); -- Register the approved operation. A different hash under the same key must be rejected by the caller. INSERT INTO signing_operation (tenant_id, operation_key, packet_hash, state) VALUES ($1, $2, $3, 'approved') ON CONFLICT (tenant_id, operation_key) DO NOTHING; -- Then SELECT the row. If packet_hash differs from $3, return a conflict. Do not proceed. -- Atomic claim: a single conditional UPDATE. Only one worker can win. UPDATE signing_operation SET state = 'claimed', claimed_by = $4, claim_expires = now() + interval '2 minutes' WHERE tenant_id = $1 AND operation_key = $2 AND packet_hash = $3 AND state = 'approved' RETURNING operation_key;This is a genuine conditional mutation, because the check and the write happen in one statement inside your own database. A read followed by a separate write would not be. Be clear about the limit, though: the call to the eSignature provider is not conditional on your claim. Unless the provider's documentation specifies a deduplication or client-reference mechanism, concurrency safety on the provider side depends on your claim discipline and on reconciliation, not on the provider.
Worker logic and ambiguous timeouts
async function sendApproved(tenantId, operationKey, expectedHash) { const op = await db.claim(tenantId, operationKey, expectedHash); // conditional UPDATE above if (!op) return 'not_claimable'; const bytes = await vault.getBytes(op.docRef); if (sha256(bytes) !== op.docHash) return db.markFailed(op, 'stored_bytes_changed'); try { // Field names are hypothetical. Confirm against the official API documentation. const res = await provider.createSignRequest({ ...op.request, clientRef: op.opaqueRef }); await db.markSent(tenantId, operationKey, res.requestId); } catch (err) { if (isDefinitiveRejection(err)) await db.markRejected(tenantId, operationKey); else await db.markUnknown(tenantId, operationKey); // timeout, reset, 5xx } }Never blindly retry from unknown. A separate reconciliation job queries the provider using whatever status or listing capability its documentation offers, and matches on an opaque reference you control. Treat the outcomes this way:
| State | Meaning | Allowed next step |
|---|---|---|
| approved | Hash approved, nothing attempted | Claim |
| claimed | One worker holds it | Send, or move to unknown if the claim expires without a recorded outcome |
| sent | Provider confirmed a request exists | Wait for completion events |
| unknown | Completion of the send could not be confirmed. This is neither success nor verified failure | Reconcile first. Re-queue only after repeated, authoritative negative checks, otherwise escalate to a person |
| bound_verified | Signed result confirmed against the approved packet | Release downstream actions |
| binding_unverifiable | Could not confirm the content match | Hold downstream actions, route to review |
| binding_mismatch | Evidence shows a different document | Terminal. Quarantine and involve legal |
Absence from a provider query can mean "not created" or "not yet visible." That is why the table requires repeated negative checks before re-queuing.
Webhooks: verified acknowledgment
When the provider reports a state change, verify the event using the method in the current documentation. eSignly's published integration pages describe signed webhook events and event types such as viewed, signed, and completed, but you should follow the official verification instructions rather than this article. Then, in a single database transaction, do three things: insert the event into a durable inbox with a unique constraint on tenant and provider event ID, record the work to be done in an outbox or job table, and commit. Only after the commit should the handler return a success status. If the transaction fails, return an error status so the provider retries. Acknowledging first and recording later turns a crash into silent data loss. The dead-letter and replay design covers events that exhaust their retries.
Completion verification
Treat the webhook as a prompt, not as proof. Fetch the authoritative request state from the API, then run the checks you can support:
- The signer set and completion state match the packet and the provider's current record.
- The template reference and field values match what you recorded, as far as the provider exposes them.
- If the provider's evidence includes a hash or fingerprint of the original document, compare it to your document hash.
- If it does not, record the result as
binding_unverifiablefor that check and rely on your stored, hashed copy of what you sent.
A signed PDF will differ at the byte level from the file you uploaded, because it now carries signature data. Do not expect a byte-for-byte match with the signed output unless the provider documents one. Hashing the signed artifact on receipt is still useful. It lets you detect later changes in your own archive.
Choosing How Strictly to Bind: Exact Bytes, Pinned Templates, or Unpinned Templates
Key point: The strictest option is also the simplest to reason about. Use looser options only when you can name the drift you are accepting.
Comparison of three binding strategies
| Dimension | A: Send exact approved bytes | B: Provider template, pinned and checked | C: Provider template, unpinned |
|---|---|---|---|
| How it works | You render and approve a file, hash it, and upload exactly that file | You record template reference and version evidence, merge-data hash, and verify before send and at completion | You reference a template identifier and merge data at send time |
| Drift exposure | Lowest. The sent bytes are the approved bytes | Medium. Depends on what version evidence the provider exposes | Highest. Any template edit changes live content |
| Engineering effort | Moderate. You own rendering and storage | Higher. You own pinning, comparison, and exception handling | Lowest |
| Speed to launch | Moderate | Slower | Fastest |
| Scalability | Good. Storage and rendering scale with your infrastructure | Good, with more states to manage | Good technically, weak on governance |
| Hidden failure mode | Rendering differences between preview and final file | Version evidence unavailable, leaving checks unverifiable | Silent edits propagate to open and future requests |
| Fits best | Contracts, regulated records, high-value agreements | High-volume standard forms with managed templates | Low-stakes documents where wording changes are acceptable |
eSignly's published API overview describes sending requests from reusable templates with signer roles, and eSignly lists PDF, DOC, and DOCX uploads as a request option. That means both strategy A and strategy B are plausible shapes for an integration. Which one fits depends on what version evidence you can capture in your account. Verify that against the current documentation and your plan rather than assuming it.
Recommendation by persona
- Backend lead at a regulated or contract-heavy company: Start with A for consequential documents. It removes an entire category of drift.
- Platform architect running thousands of near-identical forms: Use B, and make "unverifiable" a first-class state with a review queue.
- Product team prototyping: C is acceptable only for non-consequential documents, with the limitation written down.
Mandatory go/no-go controls
Use this as an all-required gate for consequential documents. A single missing control is a no-go. Passing every control does not certify that your system is production-ready or legally compliant. It only means this particular gap has been addressed.
| # | Control | Evidence to show |
|---|---|---|
| 1 | Approval is recorded against a packet hash, never only against a business object | Schema and a sample approval row |
| 2 | Operation keys are tenant-scoped, and reuse with a different hash is rejected | Test that returns a conflict |
| 3 | Work is claimed with a single conditional write, so concurrent workers cannot both send | Concurrency test with parallel workers |
| 4 | Ambiguous send outcomes move to unknown and are reconciled before any retry | Fault-injection test with a forced timeout |
| 5 | Retries reuse stored approved content and never re-render from live data | Code review plus a test with changed source data |
| 6 | Webhooks are acknowledged only after inbox and work records commit atomically | Test that kills the process before commit |
| 7 | Completion has three outcomes: verified, unverifiable, mismatch. Downstream actions run only on verified | Handler tests for all three |
| 8 | Every stored identifier has a named owner, retention rule, and erasure path | Data inventory entry |
The failure injection plan for pre-launch testing is a useful starting point for controls 3, 4, and 6.
Risks, Legal Scope, and a Lower-Risk Rollout
Key point: A hash proves that bytes did not change. It does not prove who signed, why, or whether the signature is enforceable.
What the design does not do
- Identity and intent: Binding content says nothing about whether the right person signed or intended to sign. Those depend on your authentication, consent capture, and the provider's signing ceremony.
- Legal validity: Enforceability depends on jurisdiction, document type, and facts. This article is not legal advice. Involve counsel for your documents and regions.
- Vendor compliance: Vendor certifications and compliance-support features describe the vendor's platform, not your whole workflow. eSignly publishes its security and compliance positions on its security page and compliance page. Review their scope, request current reports where you need them, and map them to your own obligations.
Where regulation touches this design
For regulated records, the principle of linking signatures to records is explicit. 21 CFR 11.70 on signature and record linking requires that electronic signatures be linked to their respective electronic records so that they cannot be excised, copied, or otherwise transferred to falsify a record by ordinary means. Whether a given workflow meets Part 11 depends on your validation, procedures, and controls, and that is your obligation as the regulated party.
On the record-retention side, the U.S. ESIGN Act addresses retained electronic records in 15 U.S.C. 7001. In general terms, an electronic record kept to satisfy a retention requirement should accurately reflect the information in the original and remain accessible and reproducible. Your stored, hashed copy of what was sent supports that goal. Applicability varies by document type and state law, so confirm with counsel.
A lower-risk rollout
- Inventory drift points. For your top three document types, list who can change the template, the data sources, and the signer mapping between approval and send.
- Add the packet and hash. Introduce the packet hash and an immutable approval record before changing anything else. Run it in observe-only mode and log mismatches.
- Enforce at send time. Add the atomic claim and the hash check. Reject sends whose hash no longer matches an approval.
- Add reconciliation. Introduce the
unknownstate and the reconcile job, and remove any retry path that rebuilds payloads. - Gate completion. Make downstream actions depend on a verified binding result. Route unverifiable results to a named reviewer.
- Test and assign ownership. Run the failure-injection tests, and assign an owner for template changes, the ledger, and the retention of every stored identifier.
2027 Update: automated and AI-assisted document assembly
More teams now let automated systems, including AI-assisted tools, draft or assemble contract text. The approval-to-signature gap widens when the content is generated rather than selected from a fixed template, because there is no stable template identifier to pin. The principle stays the same regardless of tooling: approve a specific content hash, and let the send path refuse anything else. If an agent has access to signing actions, see the proposed approval gate design for MCP access.
Want to test this pattern against a real API?
Start with a small, non-production workflow. Check the template, signer role, and webhook behavior before you commit.
Explore eSignly's eSignature API plans and begin with a free account.
Free TrialYou can also review the eSignly API overview for the current request flow, then confirm plan eligibility and testing options for your account.
Conclusion: Five Actions to Close the Approval-to-Signature Gap
The goal is simple: be able to show, for any signed document, which approved content it came from, and know when you cannot show it. These five actions get you there without a rewrite.
- Move approval onto content. Record every approval against a packet hash, and treat any change as a new approval.
- Choose the strictest binding you can afford. Send exact approved bytes for consequential documents. Use pinned templates only where you can name the drift you accept.
- Make the send path single-winner and reconcile-first. Bind tenant-scoped operation keys to hashes, claim work with one conditional write, and treat ambiguous outcomes as unknown.
- Gate downstream actions on verified binding. Use three completion outcomes, and never let "unverifiable" behave like "verified."
- Assign owners and take legal advice. Name an owner for templates, the ledger, and every stored identifier. Have counsel review your document types and regions.
About this guidance
eSignly has provided online eSignature and eSignature API services since 2014. Our team works with legal, compliance, operations, and engineering teams on signing workflows, audit trails, and integrations. For eSignly's published security and compliance statements, see the security and compliance pages linked above. This article was reviewed by the eSignly Expert Team.
Frequently Asked Questions
Does hashing a document before sending make the eSignature legally valid?
No. A hash supports content integrity. It helps show that the bytes you sent are the bytes you approved. Legal validity depends on factors such as signer intent, consent, identity, the applicable law, and the type of document. Treat the hash as one evidence layer and consult counsel about the rest.
Can I rely on the provider's template identifier to prove the content did not change?
Not by itself. An identifier names a template, but it may not capture whether the content behind that name changed. Record any version evidence the provider exposes, hash the merge data, and compare at send time and completion. If version evidence is unavailable, mark the check as unverifiable instead of assuming it passed.
What if the API does not return a hash of the original document?
Then your binding is internal. Keep the exact bytes you sent in controlled storage, record their hash in your ledger, and hash the signed artifact when you receive it. At completion, report "unverifiable at provider level" for the document-match check. Do not report it as verified.
How should I retry after a timeout when creating a signing request?
Do not retry immediately. Mark the operation as unknown, then reconcile against the provider's authoritative state using its documented status or listing capability and an opaque reference you control. Re-queue only after repeated negative checks, and always reuse the stored approved content instead of re-rendering from live data.
Should I store merge data and signer emails in the ledger?
Prefer storing keyed hashes and opaque identifiers rather than raw values. Plain hashes of low-entropy data can be guessed back, and even hashes or identifiers linked to people can be sensitive. Give each stored field an owner, a retention rule, and an erasure path.
Is this level of control necessary for low-risk documents?
Often not. For low-stakes documents, an unpinned template may be acceptable if the business accepts that wording can change. Write that decision down. For contracts, regulated records, and anything with financial or legal consequences, the binding controls are worth the effort.
Does this pattern change for on-premises deployments?
The ledger pattern lives on your side of the integration, so the core ideas carry over: approve against a hash, claim sends atomically, and reconcile unknown outcomes. Endpoints, event delivery, and available evidence can differ by deployment, so confirm those details in the documentation for your specific setup.
Is your approved contract the one your signer actually sees?
Close the gap between approval and signature with a send path you can verify. Prototype it on a real eSignature API before it matters.
Talk to eSignly about API plans, templates, and webhook setup for your workflow.
Free TrialResource Esignature Api Guide
This article is most relevant for CTOs and developers who need to roll out a practical signing workflow. Use the related eSignly path to compare plans, API options, compliance fit, and implementation next steps.
Reviewed for electronic signature decision makers
This guide is reviewed for clarity, legal and operational relevance, service alignment, and practical conversion path before being connected to an eSignly plan or API workflow.
For regulated, high-volume, or customer-facing workflows, validate legal duties, plan assumptions, and integration requirements with your internal stakeholders before rollout.

