Vantage Example

A diagnostics storefront and ops console on the Vantage API: order blood and DNA test kits, track fulfilment, and deliver FHIR results.

Terra Dispatch is a white-label diagnostics storefront with an operations console behind it, built on the Vantage API. It covers the full kit lifecycle: browse a catalog, place an order, activate a kit, track fulfilment, and deliver results with the acknowledgment step Vantage requires.

It runs against the hosted sandbox, with no cloud accounts to set up. Without credentials it starts in demo mode on captured sandbox data.

terra examples clone vantage-web-app my-app
cd my-app && npm install && npm run dev

/shop is the storefront your end users would see. /ops is your team's console: analytics, orders, lifecycle simulation, the results queue, and a webhook inbox. The switch between them is a demo device, and the example deliberately ships no auth framework.

What it demonstrates

• Catalog browse and curation, showing the biomarkers each kit measures, plus AT_HOME and GO_TO_LAB ordering with draw-site lookup

• Kit activation, both hosted and programmatic

• Signed webhooks with verification, an inbox, and delivery-outcome debugging

• Order tracking with full status history

• FHIR result parsing and display

• The mandatory results acknowledgment flow and escalations

• Sandbox lifecycle simulation, to drive an order through every state without a real kit

Run it yourself

Prerequisites: Terra CLI, Node.js v20+. Demo mode needs nothing else. For the sandbox you need a Terra Dev ID and API key with Vantage access, which the Terra team enables. See account setup.

1

Start in demo mode

terra examples clone vantage-web-app my-app
cd my-app
npm install
npm run dev

The API runs on port 8787 and the SPA on 5173. Open http://localhost:5173 for a read-only walkthrough on real captured sandbox data.

2

Point it at the sandbox

Copy .env.example to .env and fill in TERRA_DEV_ID and TERRA_API_KEY. You can now browse the live catalog and place sandbox orders. npm run setup checks your env and names every key.

3

Drive an order

Place an order in /shop, then use the simulate panel in /ops to move it through collection, lab receipt, and results. Updates arrive by polling unless you set up webhooks.

4

Receive webhooks

Add TERRA_SIGNING_SECRET to .env, install the ngrok CLI, then run npm run webhook:tunnel. It opens a tunnel, registers the URL with Vantage, and events land in /ops/webhooks.

How the integration works

src/server/lib/vantage/ holds one capability per file, each dependency free so you can lift it into your own backend.

Webhook verification is the piece most worth copying. Vantage sends X-Terra-Signature: t=<unix_seconds>,v1=<hex>, where v1 is an HMAC-SHA256 of ${t}.${rawBody}. Three details matter: t is in seconds, not milliseconds; the HMAC covers the raw body, so verify before parsing JSON; and the comparison has to be constant time.

src/server/lib/vantage/webhook-signature.ts

const nowSeconds = (opts.now ?? (() => Date.now() / 1000))();
if (Math.abs(nowSeconds - t) > (opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
  return false;
}

const expected = createHmac("sha256", signingSecret)
  .update(`${t}.${rawBody}`)
  .digest("hex");

const a = Buffer.from(expected, "utf8");
const b = Buffer.from(received, "utf8");
return a.length === b.length && timingSafeEqual(a, b);

If you already use the terra-api SDK for the Unified API, its verifyTerraWebhookSignature covers the same scheme.

Explore the code

View the source

Includes tests over signature verification, FHIR parsing, and error triage. AGENTS.md carries a "copy this, not that" map.

Path	What it holds
src/server/lib/vantage/webhook-signature.ts	Signature verification; start here
src/server/lib/vantage/client.ts	API client and typed responses
src/server/lib/vantage/orders.ts	Order creation and status history
src/server/lib/vantage/results.ts	Result retrieval and acknowledgment
src/server/lib/vantage/fhir.ts	FHIR parsing into displayable results
src/server/lib/vantage/simulate.ts	Sandbox lifecycle simulation
src/server/lib/vantage/reconcile.ts	Reconciliation against Vantage