Agent skill

Terra API Webhooks Skill

Receive and verify Terra API webhooks (tryterra.co wearables and health data). Use when setting up a Terra webhook destination, debugging terra-signature verification, or handling events like auth, deauth, user_reauth, access_revoked, connection_error, activity, sleep, body and daily.

Install this skill

npx skills add hookdeck/webhook-skills --skill terra-api-webhooks


When to Use This Skill

  • How do I receive Terra API webhooks?
  • How do I verify the terra-signature header (t=...,v1=...)?
  • How do I handle Terra auth, deauth or activity events?
  • Why is my Terra webhook signature verification failing?
  • How do I dispatch on the type field of a Terra webhook body?

Essential Code (USE THIS)

Terra signs every delivery with the terra-signature header:

terra-signature: t=1723808700,v1=a5ee9dba96b4f65aeff6c841aa50121b1f73ec7990d28d53b201523776d4eb00
  • t is the Unix timestamp (seconds). Use it as the string in the header; never parse and re-format it.
  • v1 is lowercase hex HMAC-SHA256 of "<t>.<raw body>". The key is the destination's signing secret as UTF-8 bytes (not hex- or base64-decoded). The header can carry several v1 values (for example during key rotation): accept the delivery if any matches. Ignore other keys such as v0.
  • The event name is the top-level type field in the JSON body; status qualifies it.
  • Missing header, no t, malformed or non-matching signature: return 401.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyTerra(rawBody, header, secret) {
  if (!secret || !header) return false;
  let t;
  const sigs = [];
  for (const item of header.split(',')) {
    const i = item.indexOf('=');
    if (i <= 0) continue;
    const key = item.slice(0, i).trim(), value = item.slice(i + 1).trim();
    if (key === 't' && t === undefined) t = value;
    else if (key === 'v1') sigs.push(value);
  }
  if (!t || sigs.length === 0) return false;
  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'));
  // Check length and alphabet first; never Buffer.from(sig, 'hex') on unvalidated input
  return sigs.some((s) => /^[0-9a-fA-F]{64}$/.test(s) &&
    crypto.timingSafeEqual(Buffer.from(s.toLowerCase()), expected));
}

Verification (Python)

import hashlib, hmac, re

def verify_terra(raw_body: bytes, header, secret: str) -> bool:
    if not secret or not header:
        return False
    t, sigs = None, []
    for item in header.split(","):
        key, sep, value = item.partition("=")
        key, value = key.strip(), value.strip()
        if not sep or not key:
            continue
        if key == "t" and t is None:
            t = value
        elif key == "v1":
            sigs.append(value.encode())
    if not t or not sigs:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest().encode()
    return any(re.fullmatch(rb"[0-9a-fA-F]{64}", s) and hmac.compare_digest(s.lower(), expected) for s in sigs)

Terra's docs don't spell out an age limit. The examples leave the timestamp check off by default, because Hookdeck retries and replays (and Terra's own retries) resend the original t, so a fixed window would reject legitimate redeliveries. Set TERRA_WEBHOOK_TOLERANCE_SECONDS to a positive number to opt in (t is Unix seconds). Dedupe on the user and payload identifiers instead.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

Dispatch on the body's type field. Terra documents 20 types; the examples handle the common ones and log the rest.

Event (type)Description
authA user connected a device or provider (status says whether it succeeded)
deauthA user disconnected
user_reauthA user re-authenticated; the user ID may have changed
access_revokedThe user revoked access at the provider
connection_errorA provider connection failed
activityNormalised workout data
sleepNormalised sleep data
bodyBody metrics (weight, heart rate, glucose, ...)
dailyDaily summary
athleteProfile data

Others include google_no_datasource, processing, large_request_sending, large_request_processing and rate_limit_hit. In ping mode a data delivery carries "type": "s3_payload" and a download URL instead of the data. See references/overview.md.

For the full event reference, see Terra's webhook docs.

Important Headers

HeaderDescription
terra-signaturet=<unix seconds>,v1=<hex>[,v0=<hex>]

Environment Variables

TERRA_WEBHOOK_SECRET=your_terra_signing_secret   # dashboard -> Connections page
TERRA_WEBHOOK_TOLERANCE_SECONDS=0   # optional; a positive value opts in to the replay window

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 terra-api --path /webhooks/terra-api

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →