Terra Basecamp

A complete Terra integration you can run yourself: wearable connections, webhook ingestion, multi-device deduplication, a live dashboard, and an AI health assistant.

Terra Basecamp is a complete health data platform built on Terra, and the first app in the terra-examples repository. Users connect their wearables (Garmin, WHOOP, Oura, and more) and the app merges their data into a daily dashboard, with an AI assistant on top.

Scaffold your own copy with one command, deploy it, and use it as a starting point for your own app:

npm create tryterra-app

What it demonstrates

• User authentication from a custom UI, with reference_id linking

• Webhook ingestion with signature verification and deduplication

• Authentication event handling: auth, deauth, reauth, and permission changes

• Historical backfill: 30 days of history when a device connects

• Multi-device deduplication by provider priority

• Scheduled reconciliation every 6 hours via cron

• An AI health assistant built on Terra's MCP tools

The dashboard summarises daily scores and insights across every connected device

The AI assistant queries health data through Terra's MCP tools, runs analysis, and renders inline charts

The Trends page charts changes in your biomarkers over time

Tech stack

The whole app runs as a single Cloudflare Worker, with end-to-end type safety from Hono RPC.

Layer	Technology
Frontend	React 19, Vite 7, TanStack Router, TanStack Query, TanStack Store
UI	React Aria Components, Tailwind CSS v4, tailwind-variants
Backend	Hono on Cloudflare Workers
Database	Neon Postgres, Drizzle ORM
Auth	BetterAuth (email OTP)
AI	LLM assistant using Cloudflare Durable Objects (via Vercel AI SDK)
Provisioning	wrangler + neonctl (Cloudflare & Neon CLIs)

Run it yourself

Run the app end to end: deploy your own copy, connect a wearable, and see health data flow from the provider to the dashboard and the AI assistant.

1

Set up and deploy

Scaffold the app and run the setup wizard:

npm create tryterra-app
cd my-app
npm run setup

npm run setup signs you in to Cloudflare and Neon through your browser, prompts for your Terra credentials, provisions a Neon database, a Cloudflare Worker, and an R2 bucket, runs migrations, and deploys the app. When it finishes, it prints your App URL. Keep that handy for the next step. Re-running it is idempotent, so it only asks for what's missing.

Prerequisites: Node.js v20+, a free Neon account, and a free Cloudflare account with R2 enabled. Setup signs you in to both through your browser, so there are no keys to copy. It also asks for your Terra dev-id, API key, and webhook signing secret from the dashboard (the signing secret lives on your webhook destination under Connections). The AI assistant is optional: it needs an Anthropic API key and the Cloudflare Workers Paid plan; without them the rest of the app runs on the free plan. SendGrid is optional too (without it, OTP codes are logged to the console). The repository README covers every environment variable.

2

Point Terra webhooks at your app

In the Terra dashboard, set your webhook destination URL to your deployed Worker:

https://<your-app-url>/api/terra/webhook

Terra now delivers authentication events and health data straight to your copy of the app.

3

Sign in

Open your App URL in a browser and sign in with your email address.

If you didn't configure SendGrid, the one-time code isn't emailed. Stream the Worker logs (for example with npx wrangler tail from your project) and read the code there.

4

Connect a wearable

Open the Connectors page, pick your provider (Garmin, WHOOP, Oura, Fitbit, and more), and complete the provider's sign-in flow. When you're redirected back, Terra sends an auth webhook, the app links the connection to your account, and a 30-day historical backfill starts automatically.

Pick a provider on the Connectors page and complete its sign-in flow

5

Watch your data arrive

Open the Dashboard. As Terra delivers the backfill and new updates, your steps, heart rate, HRV, sleep, and stress fill in. Delivery timing varies by provider. If you connect a second device, overlapping data is merged by provider priority.

Each connector's detail page lists enabled scopes and recent sync events as Terra delivers your data

6

Ask the AI assistant

Open Chat and ask about your data. Try "How did I sleep this week?" or "Chart my steps for the last 30 days". The assistant queries your data through Terra's MCP tools and renders inline charts.

Chat needs an ANTHROPIC_API_KEY (added during setup) and the Cloudflare Workers Paid plan. Without it, the rest of the app still works.

Develop locally with npm run dev (it runs against a separate dev database branch, so you can't break your deployed data), and ship changes with npm run deploy.

How the Terra integration works

Two pieces are worth calling out. First, the webhook endpoint verifies Terra's signature against the raw request body before parsing JSON, then returns 200 immediately and processes the event asynchronously to stay inside Terra's webhook timeout.

import { verifyTerraWebhookSignature } from "terra-api";

const terraWebhook = new Hono<{ Bindings: Env }>().post("/", async (c) => {
  // Raw body required: verify the signature before JSON parsing
  const rawBody = await c.req.text();
  const signature = c.req.header("terra-signature");

  try {
    await verifyTerraWebhookSignature(rawBody, 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 });
});

Second, the AI assistant connects to the Terra MCP server that Terra exposes per connection, then hands those tools straight to the model alongside its own chart-rendering tool, so the LLM can fetch a user's data and visualise it in one turn.

// Terra exposes an MCP server per connection
const url = `https://access.tryterra.co/api/v2/mcp/${terraUserId}`;
await this.addMcpServer("terra", url, {
  transport: { headers: { "dev-id": env.TERRA_DEV_ID, "x-api-key": env.TERRA_API_KEY } },
});

const result = streamText({
  model: anthropic(CHAT_MODEL),
  messages: modelMessages,
  tools: { render_chart: renderChartTool, ...this.mcp.getAITools() },
});

Explore the code

The full source is on GitHub, including tests alongside the webhook, sync, and backfill modules. The repository also ships its own guides:

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