terra-unified-api

Verify the terra-signature or X-Terra-Signature header (read case-insensitively) as an HMAC-SHA256 over the raw, unaltered request body before any JSON parsing. Re-serializing a parsed body breaks verification, so capture raw bytes first and reject invalid signatures with 401.

Deduplicate on the X-Terra-Trace-Id header, which uniquely identifies each delivery and stays stable across retries. Do not dedupe on terra-reference, since every chunk of a large request shares it and later chunks would be silently dropped.

data_enrichment scores do not follow the superset guarantee, so a later webhook can carry null scores for a day that previously had values. Upsert score columns with COALESCE(excluded.col, table.col) so incoming nulls never overwrite stored values.

Terra API issues a new Terra user ID and sends a user_reauth event containing both old and new IDs. You must swap the stored ID in place, or future webhooks will not match any known connection and the old connection appears active forever.

Key activity and sleep rows by metadata.summary_id, and daily, body, nutrition, and menstruation rows by (connection, date) using the date sliced from the ISO string before timezone conversion. Extract metrics into typed columns and archive raw payloads in object storage linked by a payload_key.

Yes. Mock the terra-api SDK, database client, and background-task scheduling at module boundaries, making async processing eager. Use terra events resend from the Terra CLI to replay real stored payloads against your endpoint for realistic coverage.