Skip to main content
Engineering checklist: building and validating integration maturity, tamper‑evident audit trails, offline mobile sync, and automated billing for appraisal platforms

Engineering checklist: building and validating integration maturity, tamper‑evident audit trails, offline mobile sync, and automated billing for appraisal platforms

A vendor‑neutral validation playbook for platform designers, engineering leads, and product managers answering AMC due‑diligence questions

Most appraisal platform demos look great until someone from engineering on the AMC side asks three questions: Show me your webhook retry behavior. Prove the audit log hasn't been edited. What happens when an appraiser is offline for six hours in a rural county?

That's where a lot of vendors fall apart. The sales deck says "full API integration" and "complete audit trail," but there's no way to actually validate any of it. This checklist is the opposite of a sales deck — it's the acceptance criteria and test cases you'd run in the real world, whether you're building the platform or evaluating one.

If you want the buyer-side framing rather than the engineering-side framing, the companion piece compares platforms on these same four capabilities at a feature level. This article goes a layer deeper: concrete contract snippets, test definitions, and pass/fail thresholds. For the offline conflict-resolution patterns that underpin section three, the offline-first mobile workflows and conflict resolution guide is worth having open in another tab.

How to use this brief

Each of the four capabilities below has the same shape: required behaviors, a contract or schema snippet, and acceptance criteria written as things you can actually test. Treat the acceptance criteria as literal gates. "The API supports webhooks" is not a gate. "A webhook that returns 500 is retried with exponential backoff and surfaces in a dead-letter queue within 15 minutes" is a gate.

Worth naming upfront: the capabilities that pass a scripted demo and fail in production are almost always the ones involving time and failure. Idempotency under retries. Audit integrity after a database migration. Sync after a long offline window. Build your test data around failure, not the happy path.

1. API maturity checklist

The appraisal integration surface is more varied than people expect. AMCs push assignments in, pull status and deliverables out, and increasingly want event streams rather than polling. A mature API covers all three directions without forcing partners to poll your status endpoint every 30 seconds.

Required endpoints (minimum viable surface)

  1. POST /assignments — create an order, returns assignment ID and idempotency acknowledgment
  2. GET /assignments/{id} — full status, current milestone, assigned appraiser
  3. PATCH /assignments/{id} — update due dates, fees, special instructions
  4. GET /assignments/{id}/deliverables — list of report versions with hashes
  5. POST /webhooks — register a subscription with event filters
  6. GET /events?since={cursor} — replayable event feed for partners who prefer pull

That last endpoint matters more than it looks. Webhooks fail. If a partner's endpoint is down for an hour, they need a way to catch up without you manually replaying events. A cursor-based event feed is the recovery path.

Webhook semantics

Webhooks are where most appraisal platforms are quietly broken. Common failures in real integrations: no signature on the payload, no retry on failure, and no way for the receiver to tell a replay from a first delivery.

{ "eventid": "evt01HQ8...", "eventtype": "deliverable.completed", "occurredat": "2026-03-14T18:22:04Z", "idempotencykey": "evt01HQ8...", "deliveryattempt": 1, "data": { "assignmentid": "asg7741", "deliverableversion": 3, "sha256": "9f2b...c01a" }, "signature": "t=1710440524,v1=5257a8..." }

The signature field is non-negotiable. Sign with HMAC-SHA256 over the raw body plus a timestamp, and reject payloads where the timestamp is older than five minutes to block replay attacks.

Retry policy acceptance criteria:

  1. Non-2xx responses retried with exponential backoff (e.g., 1m, 5m, 30m, 2h, 6h)
  2. After final retry, event lands in a dead-letter queue visible to the partner
  3. Each retry carries the same eventid and an incremented deliveryattempt

Auth, versioning, and limits

OAuth2 client credentials for server-to-server; short-lived JWTs for session contexts. Avoid long-lived static API keys as the only option — if a key leaks, rotation shouldn't require a partner code deploy.

ConcernWeak implementationAcceptance criterion
AuthSingle static API keyOAuth2 + rotatable credentials, scoped tokens
Versioning"We're backward compatible" verballyPublished version + 12‑mo deprecation window
Rate limitsUndocumented, 429s with no headersDocumented limits, Retry-After + remaining-quota headers
IdempotencyNone on createIdempotency-Key header honored for 24h+
SandboxNoneFull sandbox with seedable test fixtures

Idempotency test

Send the same POST /assignments with an identical Idempotency-Key three times in rapid succession. Pass: one assignment created, two responses return the original resource. Fail: two or three assignments created. This single test catches more real-world billing and duplication bugs than almost anything else in this document.

2. Audit‑trail design and validation

An audit trail that can be edited is not an audit trail. For appraisal work, where files surface in litigation and regulatory reviews years later, "append-only" has to be provable — not just asserted in a readme.

Immutable event model

Every meaningful action writes an event to an append-only store. No updates, no deletes — corrections are new events that reference the prior one. Required fields on each event:

  1. event_id (globally unique)
  2. actor (user ID, service account, or system)
  3. occurred_at (timestamp with timezone offset, not naive local time)
  4. source (which subsystem emitted it)
  5. payload (the change itself)
  6. prev_hash (hash of the previous event in the chain)
  7. hash (hash of this event's canonical form including prev_hash)

{ "eventid": "aud0192...", "actor": "user441", "occurredat": "2026-03-14T13:22:04-05:00", "source": "report-service", "action": "narrative.edited", "payload": { "section": "reconciliation", "fieldlendelta": 212 }, "prev_hash": "8c1f...aa90", "hash": "e77b...12dc" }

Tamper evidence that holds up

Hash chaining catches edits internally. For external defensibility, periodically anchor the chain: compute a Merkle root over a batch of events (say, daily) and sign it with a key held outside the application database. Some teams anchor the daily root to a notarization service or a timestamping authority. The point is that an attacker who compromises the application DB still can't forge a valid signed root.

One timezone issue that consistently bites people: storing occurred_at without an offset makes forensic reconstruction unreliable across daylight-saving boundaries. A review signed at "1:30 AM" during the fall-back hour is genuinely ambiguous without the offset. Always store offset-aware timestamps.

Retention and export

Export formats should match who's asking. Attorneys want PDF with a cover page and verification instructions. Engineers and analysts want JSONL so they can replay. Spreadsheet-driven reviewers want CSV. Support all three, and include the signed Merkle root in the export so the recipient can verify independently.

Forensic reconstruction test cases

  1. Chain integrity

    Pull the full event chain for one assignment, recompute each hash from prev_hash, confirm the final hash matches the signed root. Pass = zero mismatches.

  2. Tamper detection

    In a test environment, manually edit one historical payload in the store, re-run verification. Pass = verification fails and points to the first broken event.

  3. Reconstruction

    From the event chain alone, rebuild the state of a report at a specific past timestamp. Pass = reconstructed state matches a snapshot taken at that time.

If test two doesn't fail loudly, your tamper evidence is decorative.

3. Offline mobile sync checklist

Field inspection is the hard part. Appraisers work in basements, rural dead zones, and new construction with no signal. The data model has to assume offline is the normal state, not the exception. The design patterns for merge strategies are covered in depth in the offline-first mobile workflows guide — this section is the validation layer on top of those patterns.

Data partitioning and partial sync

Don't sync the whole database to a phone. Partition by assignment and sync only what the appraiser has active, plus reference data (comps, forms) that's reasonably small. A full-sync-only design falls over the moment an appraiser has 40 active files and a slow connection.

Sync metadata every record needs

  1. record_id and version (monotonic per record)
  2. updated_at (device clock, offset-aware)
  3. server_seq (assigned on successful sync)
  4. deleted tombstone flag (never hard-delete offline-mutable records)
  5. device_id (which device made the change)

Tombstones matter because without them, a record deleted on one device reappears after sync from another device that never saw the delete.

Conflict detection and merge strategy

Detection: compare version and server_seq. If both sides changed a record since the last common version, that's a conflict. Merge strategy depends on the field:

  1. Last-write-wins — fine for simple scalar fields like a checkbox or a single measurement
  2. Per-field merge — appraiser A edits condition notes, appraiser B edits square footage; merge both rather than overwrite
  3. CRDT structures — for genuinely concurrent collaborative fields like a running notes list, where neither side should lose data

The mistake that shows up most often: last-write-wins applied blindly to an entire record. Two appraisers — or one appraiser on phone and tablet — touch the same file, and the second sync silently overwrites the first one's photo captions. The data loss is invisible until a lender exception surfaces weeks later.

Protocol: delta sync with checkpointing

Use delta sync keyed on server_seq. The client sends "last seq I have is 4412," the server sends everything after. Checkpoint frequently so an interrupted sync resumes rather than restarts — critical on bad connections where a 30-second window is all you get.

A simple diagram of delta sync with checkpointing and conflict resolution.

Process diagram

Checkpoint frequently so an interrupted sync resumes rather than restarts — critical on bad connections where a 30-second window is all you get.

Offline UX acceptance

  1. App is fully usable offline, including creating new assignments and attaching photos
  2. Pending-sync state is visible per record, not just a global spinner
  3. Conflicts surface to the appraiser with both versions shown, not auto-resolved silently when the merge is ambiguous

The long-offline test

This is the one most platforms skip. Put a device offline, make 50+ edits across 10 assignments over a simulated six-hour window, modify some of the same records from a second device and the server, then reconnect.

  1. No data loss on any record
  2. All true conflicts detected and surfaced
  3. Tombstones honored (deleted records stay deleted)
  4. Sync completes within a reasonable window and resumes if interrupted mid-stream

Run this with an artificially throttled connection and with a forced disconnect halfway through sync. If it only works on hotel wifi, it doesn't work.

4. Billing automation hooks

Billing bugs in appraisal platforms share one root cause: events that fire more than once, or not at all. Both corrupt the invoice.

Metering event types

  1. assignment.accepted
  2. deliverable.created
  3. review.completed
  4. revision.requested
  5. rush.flagged

Each metering event carries an idempotency_key. When the same deliverable.created event is delivered twice — and it will be, because retries exist — the billing engine must charge once.

{ "meterevent": "deliverable.created", "idempotencykey": "asg7741:deliverable:v3", "assignmentid": "asg7741", "billableunits": 1, "occurred_at": "2026-03-14T18:22:04Z" }

Note the idempotency key is derived from the business fact (asg_7741:deliverable:v3), not a random UUID. This way, even if the upstream system generates two separate event objects for the same deliverable, they collapse to one charge.

Webhook reconciliation

The billing provider's webhooks (charge succeeded, payment failed) need the same retry and dead-letter handling as section one. On top of that, run a daily reconciliation job: compare internal metered events against the billing provider's recorded charges, flag any delta.

Billing test cases

  1. Duplicate meter event

    Fire deliverable.created twice with the same key. Pass = one charge.

  2. Out-of-order delivery

    Deliver review.completed before deliverable.created. Pass = engine handles gracefully, no phantom charge.

  3. Reconciliation delta

    Inject a metered event that never reached billing. Pass = daily recon flags it within the tolerance window.

  4. Dispute handling

    Mark a charge disputed. Pass = future metering continues, disputed charge isolated, audit event written.

Each metering event carries an idempotency_key. When the same deliverable.created event is delivered twice — and it will be, because retries exist — the billing engine must charge once.

KPIs and acceptance criteria

These are the numbers worth putting in a contract or an internal SLO. They're ranges, not promises — tune to your scale.

CapabilityMetricTarget
APIp95 response latencyunder ~300ms for reads
APIWebhook delivery success (incl. retries)99.9%+
AuditTamper-detection rate100% (zero tolerance)
AuditChain verification failures in prod0
SyncDivergence rate (unresolved conflicts)well under 1% of synced records
SyncLong-offline data loss0
BillingReconciliation deltaunder ~0.1% of charges, auto-flagged

Set operational alerts on the ones where the acceptable value is zero: any audit chain verification failure, any long-offline data-loss event, any reconciliation delta above tolerance. Those should page someone, not sit in a dashboard.

Red flags and rollout checklist

A few implementation patterns that look fine in a demo and break in production:

  1. "We have webhooks" but no signatures or retries. The demo fires one webhook to a listening endpoint. Production has outages. Ask to see the dead-letter queue.
  2. Audit log in the same mutable table as app data. If a support engineer can UPDATE an audit row, it's not an audit trail. Ask whether it's append-only at the storage layer.
  3. Offline sync that only does last-write-wins on whole records. Ask specifically about per-field merges and run the long-offline test.
  4. Billing keyed on random UUIDs instead of business facts. Guarantees duplicate charges under retries.
  5. Naive timestamps. No timezone offset anywhere is a forensic liability.

A rollout sequence that tends to work:

  1. Stand up the sandbox and seed realistic test fixtures first.
  2. Run the idempotency and duplicate-charge tests before anything else — they catch the costliest bugs.
  3. Run the long-offline sync test with throttling and forced disconnect.
  4. Run the tamper-detection test and confirm it fails loudly.
  5. Only then wire up a real partner in a limited pilot.

When this depth is overkill

A two-person shop doing 30 orders a month through a single AMC portal doesn't need Merkle-anchored audit trails and CRDT merges. The right scope there is signed webhooks, append-only logging, and solid idempotency. The full checklist earns its keep when you're integrating with multiple AMCs, carrying files into litigation territory, or putting dozens of appraisers in the field on offline devices.

The common thread across all four capabilities: the happy path always passes. Build your acceptance tests around retries, long offline windows, tampered records, and duplicate events. That's where real platforms separate from good-looking demos — and it's exactly the ground AMC engineering teams will walk you across during due diligence.

Built for Appraisers Tailored solutions for appraisal workflows and compliance
Save Time Optimize scheduling, reporting, and communication
Delight Clients Faster turnaround and transparent updates
Grow Revenue Boost productivity and expand service capacity