Unified API Example

A complete Unified API integration: wearable connections, webhook ingestion, multi-device deduplication, a live dashboard, and an AI health assistant.

Terra Basecamp is a health data platform built on the Unified API. Users connect their wearables and the app merges the data into a daily dashboard, with an AI assistant on top. It runs as a single Cloudflare Worker backed by Neon Postgres.

terra examples clone unified-api-web-app my-app

What it demonstrates

• User authentication from a custom UI, with reference_id linking

• Webhook ingestion with signature verification and deduplication

• Authentication events: auth, deauth, reauth, and permission changes

• Historical backfill of 30 days when a device connects

• Multi-device deduplication by provider priority

• Reconciliation every 6 hours via cron

• An AI assistant built on Terra's MCP tools

The dashboard summarises daily scores across every connected device

Run it yourself

Prerequisites: Terra CLI, Node.js v20+ and free Neon and Cloudflare accounts with R2 enabled. Setup signs you in to both in the browser. The repository README lists every environment variable.

1

Deploy

terra examples clone unified-api-web-app my-app
cd my-app
npm install
npm run setup

npm run setup provisions a Neon database, a Worker, and an R2 bucket, runs migrations, deploys, and prints your App URL. It asks for your Terra dev-id, API key, and webhook signing secret from the dashboard. Re-running it is idempotent.

2

Point webhooks at your app

Set your webhook destination URL to https://<your-app-url>/api/terra/webhook.

3

Connect a wearable

Sign in with your email, open Connectors, and complete a provider's sign-in flow. Terra sends an auth webhook and a 30-day backfill starts. Without SendGrid configured, read the sign-in code from npx wrangler tail.

4

Watch it arrive

Open the Dashboard as the backfill lands. Connect a second device and overlapping data is merged by provider priority. Then try Chat: "How did I sleep this week?" Chat needs an ANTHROPIC_API_KEY and the Workers Paid plan.

Develop locally with npm run dev, which uses a separate database branch, and ship with npm run deploy.

How the integration works

The webhook endpoint verifies Terra's signature against the raw body before parsing JSON, then returns 200 immediately and processes asynchronously to stay inside Terra's timeout.

Webhook endpoint

const terraWebhook = new Hono<{ Bindings: Env }>().post("/", async (c) => {
  // Raw body required: verify the signature before JSON parsing
  const rawBody = await c.req.text();
  try {
    await verifyTerraWebhookSignature(
      rawBody,
      c.req.header("terra-signature"),
      c.env.TERRA_WEBHOOK_SECRET,
    );
  } catch {
    return c.json({ error: "Invalid signature" }, 401);
  }

  // Return 200 immediately; process async to stay within Terra's timeout
  c.executionCtx.waitUntil(processWebhookEvent(c.env, rawBody));
  return c.json({ success: true });
});

The AI assistant connects to the Terra MCP server exposed per connection and hands those tools to the model alongside its own chart tool, so it can fetch and visualise data in one turn.

Explore the code

View the source

The repository ships its own guides:

Guide	What it covers
Terra webhooks	Ingestion pipeline, archiving, idempotency
Auth & reconciliation	Connection lifecycle and the reconciliation cron
Multi-device data	Provider priority and deduplication
AI health assistant	Chat architecture, MCP tools, inline charting
Infrastructure	Provisioning and deployment