Real-Estate Document and E-Sign Workflow: Build and Test

A real-estate document workflow fails when a lease or offer is signed out of order, edited after signing, or loses its audit trail. Build it as a state machine: a document moves from draft to out-for-signature to signed to executed, and once executed it is frozen. Record every event in a tamper-evident log, let an e-sign provider handle the signature ceremony, and test that an executed document can never change.

This is general engineering guidance, not legal advice; whether an e-signature is valid for a given document and jurisdiction is a question for your adviser. If you would rather have the workflow built and tested for you, see how RAITHub would build this below.

What documents does a real-estate workflow actually move?

Offers and counter-offers, tenancy and lease agreements, disclosures and condition reports, agency agreements, and the countersigned versions of each. They differ from a generic file upload in three ways: they have parties (who must sign, and in what order), they have a status that is legally meaningful (an executed contract is not a draft), and they need a record of exactly what was signed. The off-plan sale variant, where allocations and payment plans attach to the document, is covered in the sales inventory CRM for off-plan developers; this post is about the signing lifecycle itself.

What does the signing state machine look like?

Model the lifecycle explicitly, so an illegal transition is impossible rather than merely discouraged. A document in draft can be edited; once sent it is locked for signing; after all parties sign it becomes executed and is read-only forever.

State	Meaning	Allowed next
draft	Being prepared; editable	sent, voided
sent	Out for signature; content frozen	partially_signed, declined, voided, expired
partially_signed	Some parties have signed	executed, declined, voided, expired
executed	All parties signed; read-only	(none)
declined	A party refused	draft (new version)
voided / expired	Cancelled or timed out	draft (new version)

Enforce the transitions in one place and reject anything not on the list. The pattern is the same state-machine discipline used for an 11-state listing lifecycle in listing moderation for property portals.

How do you make the signed version tamper-evident?

When a document is sent, freeze its exact bytes and store a hash. When it is executed, store the final file's hash too. Record every event, viewed, signed, declined, with who, when and from where, in an append-only log whose rows are hash-chained: each row includes the hash of the previous one, so a deleted or altered row breaks the chain and shows up. This is the approach behind the hash-chained audit log in designing an audit log customers trust.

-- The document's content is frozen on 'sent' and never updated after that.
CREATE TABLE document_versions (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id  uuid NOT NULL,
  content_hash text NOT NULL,            -- SHA-256 of the exact file bytes
  frozen_at    timestamptz NOT NULL DEFAULT now()
);

-- Append-only, hash-chained signing events.
CREATE TABLE signing_events (
  id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  document_id uuid NOT NULL,
  party_id    uuid NOT NULL,
  event       text NOT NULL,             -- viewed | signed | declined
  occurred_at timestamptz NOT NULL DEFAULT now(),
  ip          inet,
  prev_hash   text NOT NULL,             -- hash of the previous event row
  row_hash    text NOT NULL              -- hash(this row + prev_hash)
);
-- No UPDATE or DELETE grant on signing_events: it is insert-only.

Should you integrate an e-sign provider or build signing yourself?

Integrate a provider. A compliant e-signature ceremony (identity capture, consent, the signed certificate and its evidence) is a product in its own right, and most jurisdictions have rules about what makes a signature enforceable, which is a legal question, not an engineering one. Your job is the integration: send the frozen document to the provider, handle its webhooks idempotently as parties sign, and pull back the final executed file and its certificate. Treat the webhook like any money-adjacent webhook, applied exactly once even if it arrives twice (the pattern is in testing payments and webhooks end to end).

How do you prove an executed document cannot be altered?

Three tests, all gated in CI. First, a state-machine test that every illegal transition (editing a sent document, re-signing an executed one) is rejected. Second, an isolation test that a signer can see only their own documents, not another party's or another agency's. Third, a tamper test that re-computes the content hash and the event chain and fails if either no longer matches.

// tests/documents/executed-is-frozen.spec.ts
import { test, expect } from '@playwright/test'
import { tokenFor, executedDocument } from './helpers'

test('an executed document rejects any edit', async ({ request }) => {
  const token = await tokenFor('agent@test')
  const doc = await executedDocument()

  const res = await request.patch('/api/documents/' + doc.id, {
    headers: { Authorization: 'Bearer ' + token },
    data: { body: 'changed after signing' },
  })
  expect(res.status()).toBe(409) // executed is read-only
})

Buy, build or hire?

Option	What you get	Choose this when
A standalone e-sign product	Send-and-sign, outside your app	You sign a few documents and don't need them tied to deals or listings
An e-sign provider's API	The signing ceremony, embedded	You want signing inside your product but not to track the wider workflow
A custom workflow on a provider's API	The full lifecycle, audit trail and your data model, with the provider doing the ceremony	Documents are tied to listings, leases and parties and must be auditable
A managed QA team on your build	State-machine, isolation and tamper suites gated in CI	You have the workflow but "executed can't change" is not proven on every build

How long does it take to build yourself?

The signing state machine, the version freeze and a hash-chained log are roughly 1 to 2 days for an engineer who has built a state machine before; the provider integration, webhook handling and the test suite add a week or so. The main risk of doing it yourself is skipping the freeze-on-send step, so the document someone signed is not provably the document you hold, which is the one thing a dispute turns on.

Why RAITHub for this

RAITHub built BlockEstate, a multi-tenant listing and inquiry platform with document workflow, in a 6-week MVP, and runs hash-chained audit logging on Sundor Skin (530+ tests). The document, role and audit model sits inside the wider build in PropTech software development and the SaaS development service. See the real-estate industry page for context.

When you don't need us

• You sign a handful of documents a month. A standalone e-sign product is simpler and cheaper.
• Your documents don't need to tie into listings or deals. An off-the-shelf tool fits.
• You need a certified legal opinion on e-signature validity. That is for your adviser, not a development partner.

How RAITHub would build this

• Scope: a document data model with parties and versions, an enforced signing state machine, a hash-chained audit trail, an e-sign provider integration with idempotent webhooks, and read-only executed documents.
• Timeline: part of a 4 to 6-week fixed-scope first release; provider integration and full audit tooling sit in the 6 to 12-week range, in phases.
• What you receive: the state-machine, isolation and tamper suites gated in CI, runbooks, the product on accounts you own, IP assigned to you and an NDA as standard.
• Ways to buy it: a fixed-scope build, a dedicated monthly team, or a QA plan if you only need the document test suite.
• Next step: a free 15-minute technical audit, then a fixed written quote.

See the QA as a Service page, or book the free 15-minute audit. E-signature validity is general information here; confirm it with your adviser.

Documentation checked on 10 October 2026.

Frequently asked questions

How do you stop a signed document from being changed?

Freeze the document's exact bytes when it is sent for signature and store a hash, make the executed status read-only in the state machine, and record every signing event in an append-only, hash-chained log. A later edit is rejected, and any tampering with the record breaks the chain.

Should I build e-signatures myself or use a provider?

Use a provider for the signature ceremony. Identity capture, consent and the signed certificate are a product in their own right, and whether a signature is legally enforceable is a question for your adviser. Build the workflow, data model and audit trail around the provider's API.

What states should a real-estate document move through?

Draft (editable), sent (content frozen, out for signature), partially signed, executed (all parties signed, read-only), plus declined, voided and expired. Enforce the allowed transitions in one place so an executed document can never return to an editable state.

How do you make the audit trail trustworthy?

Store signing events in an append-only table with no update or delete grant, and hash-chain the rows so each includes the hash of the previous one. A deleted or altered row breaks the chain, which a verification test detects, so the record is tamper-evident.

Is an e-signature legally valid?

That depends on the document type and the jurisdiction, and it is a legal question. This post covers how to build and test the workflow soundly; confirm the validity and any formal requirements of e-signatures for your documents with your own adviser.