The signature completes and the executed copy never reaches the file

The observable is always the same. The deal team believes the agreement is signed and has an email saying so; the repository holds version 7 of a draft, marked in negotiation. The signature happened. The filing did not, and the gap between those 2 events is where every one of the 5 causes lives.

Ranked by how often each turns out to be the answer: the completion event was never subscribed to or failed silently, the executed copy came back without the evidence that it was validly executed, nothing in the envelope maps deterministically to a contract record, a multi-party envelope completed only partly, or the signature was collected on paper.

Reconcile one closed month of completions against one month of filings

Do not sample documents. Sample time. Pick a month that closed a week ago, so late filings have landed, and compare 2 lists over it.

1. List every envelope that reached completed status in the window, from the signature platform's own reporting or its API. This is the ground truth; your repository is the thing under test.
2. List every contract record whose status moved to executed in the same window, plus 3 days of tail. A ceremony finishing late on the last day of the month files on the first of the next.
3. Join the 2 lists on the envelope identifier. If you cannot, because the identifier was never stored on the record, you have found cause 3 without going further and the rest of the exercise is manual matching on counterparty and title.
4. Count 3 buckets: completed and filed, completed and not filed, filed with no completing envelope. The third bucket is not an error — it is paper, or a copy someone dropped in by hand — but it tells you how much of your execution volume never touches the platform.
5. Take 10 records from the second bucket and check your own event log for the completion event. Received and unprocessed is a different defect from never received, and only one of them is fixed in your code.

Run it once and it diagnoses. Run it monthly and it becomes the control that holds the missing count at zero, which is the real recommendation here.

The completion event fired and nothing was listening

Every signature platform will push you an event when an envelope completes, and every one of those pushes is at-least-once at best and not-at-all at worst. The failures are ordinary and they are all silent from your side of the wire.

• Signature verification broke after a key rotation. Your endpoint starts rejecting payloads it cannot authenticate, the platform retries on its schedule, the retry window closes, and the event is gone. Nothing in your logs says a contract was signed, because nothing you accepted said so.
• The endpoint acknowledged before it did the work. A handler that returns 200 on receipt and then queues, and whose consumer dies, has told the sender the event is safely delivered. Acknowledge after the durable write, never after the read.
• The subscription covers the wrong event. Recipient-level and envelope-level events are different things, and subscribing to the first causes the partial-completion problem further down this page.
• The environment moved and the subscription did not. A staging endpoint left registered after a cutover produces a system that worked in testing and receives nothing in production.

The agreement came back and the proof of signing did not

Signature platforms produce 2 artefacts at completion. One is the merged document with the signatures rendered onto it. The other is a separate record of the ceremony: who signed, how they were authenticated, the timestamps, the addresses the actions came from, and the sequence of events. A pipeline written to fetch the document is usually written to fetch only the document, and the second artefact is left on the platform.

That matters when someone disputes execution years later. The statutes giving an electronic signature its legal effect differ by jurisdiction — the US ESIGN Act with the state UETA enactments, the EU's eIDAS Regulation, India's Information Technology Act among them — so confirm the current requirements in your governing law rather than assuming them. What they have in common is weight on attribution and integrity: showing who signed, how they were identified, and that the record has not changed since. The artefact carrying that is the completion record, and if you never retrieved it you cannot produce it.

Two practical consequences. File the completion record beside the executed copy as a distinct document type, not appended to the agreement where the next person to split the file will crop it out. And store the document hash at filing, so a later question about whether the copy on your shelf is the copy that was signed has an answer that does not depend on the platform still existing, or on its retention terms, which are commercial rather than permanent.

Nothing in the envelope says which contract record it belongs to

This is the cause that survives every other fix, because it turns filing into guesswork. The completion event arrives, carries an envelope identifier, a document name and a list of signers, and none of those is your contract record id. So the integration falls back to matching on counterparty name and document title — the same entity-resolution problem that already makes counterparty reporting unreliable, now placed on the critical path of filing.

The fix is to mint the identifier before the envelope exists and carry it through. A contract record is created when the request comes in, which is one more reason the contract request form should be designed around what happens next. That id goes into the envelope's own metadata or custom fields at creation, comes back on the completion event untouched, and the filing step becomes a lookup rather than a match.

Do not try to backfill the id onto historic envelopes by inference. Name-and-date matching over an archive produces confident wrong answers at a rate nobody measures, and it is the same mechanism by which migrated contracts arrive with empty metadata that everyone then treats as authoritative. Start the discipline from a cut-off date and leave the archive honestly unlinked.

Two of five signed, and the workflow called it done

A 5-party agreement generates a recipient-level event each time somebody signs and one envelope-level event when the last of them finishes. Subscribe to the first and your repository will happily file a document as executed when 2 signatures are on it. The file looks right, opens right, and is not an executed agreement.

Guard it in your own data rather than trusting the subscription. Store the expected signer count on the record at send time, refuse the filing transition until the completion event reports that many signatures, and treat a mismatch as an exception for a person rather than a retry. The same guard catches a party signing a counterpart in a separate envelope, a signatory replaced mid-ceremony, and an envelope voided and resent while the old one sits in your queue.

File the declined and voided outcomes too. A negotiation that ended without signature is a fact the business needs, and a repository recording only successes cannot distinguish an agreement still in play from one that died in October.

The ones that were never electronic in the first place

The third bucket in the reconciliation — filed copies with no completing envelope — is where paper lives. Some counterparties will not use a platform, and some instruments still get wet-ink treatment on legal advice, because execution formalities differ by jurisdiction and by document type. Confirm what your governing law requires for the specific instrument rather than applying a general rule.

Those agreements need an explicit route, because the alternative is that they arrive by whatever path the individual invents. Give the paper path the same 3 outputs as the electronic one — the executed document, a record of how execution was evidenced, and the contract record id — and label the weaker evidence as weaker rather than storing it in the same field as a platform certificate.

A completed envelope is a fact on somebody else's server. Until your own sweep has seen it, your repository is not recording an agreement, it is guessing about one.

What to fix first, and the state the executed copy has to end in

Filing is not finished when the PDF is stored. The executed copy has to supersede the draft rather than sit beside it as one more version, so the authoritative-copy pointer moves and the drafts are demoted in the same transaction. The flattened PDF that comes back has lost every tracked change it carried — the same flattening behind a suggested redline returning as clean text — so negotiation history has to be preserved before execution, not recovered after it.

The executed copy then starts the next pipeline, from an executed PDF to a dated obligation with an owner, which can only run over documents that were actually filed. Building the webhook, the sweep and the signer-count guard as one small service is ordinary product engineering work. This page sits in the contract lifecycle from request to renewal, part of legal technology software.

• electronic signature
• contract filing
• webhooks
• audit trail