用途
Terra Webhooks 用于处理来自 Terra API 的实时健康数据推送。当用户通过 Terra 连接健康数据提供方（如 FITBIT、GARMIN、OURA 等）后，Terra 会通过 Webhook 将认证状态变化和健康数据事件推送到开发者配置的端点。该技能适用于搭建 Webhook 端点、验证签名、处理事件以及调试 Webhook 问题。
主要能力
签名验证
Terra 使用 HMAC-SHA256 对 Webhook 请求签名。请求头 terra-signature 的格式为 t=1234567890,v1=abc123...。验证时需将时间戳与原始请求体拼接为 {timestamp}.{body}，使用签名密钥计算 HMAC-SHA256，并与 v1 值进行常量时间比较（hmac.compare_digest）以防止时序攻击。签名密钥从 Terra 控制台获取。
事件类型
认证事件：auth（用户成功连接）、deauth（用户断开连接）、user_reauth（用户重新认证）、access_revoked（提供方撤销访问）、connection_error（连接失败）。
数据事件：activity（新的锻炼/活动数据）、sleep（新的睡眠会话数据）、body（身体指标更新）、daily（每日摘要更新）、nutrition（营养/餐食数据）、menstruation（周期追踪数据）、athlete（用户资料更新）。
处理事件：processing（数据正在处理）、large_request_processing（大请求处理中）、large_request_sending（大请求分块发送）。
事件负载
各事件负载包含 type、user（含 user_id、provider、reference_id 等）以及 data 数组。例如 activity 事件包含 metadata（起止时间、类型）、calories_data、heart_rate_data、distance_data；sleep 事件包含 sleep_durations_data、asleep 等字段；daily 事件包含 movement_data、calories_data。
异步处理
示例使用 Celery 将 Webhook 负载放入队列异步处理，端点立即返回 200，以满足 Terra 建议的 5 秒内响应要求。
幂等性
针对重复推送，示例按事件类型生成幂等键：activity/sleep 使用 user_id:start_time:end_time；daily/body 使用 user_id:日期；认证事件使用 user_id:type:时间戳。处理前检查是否已处理，避免重复写入。
重试逻辑
Terra 对失败的 Webhook 进行重试，共约 8 次，跨越 24 小时以上：第 1 次立即，第 2 次约 30 秒，第 3 次约 2 分钟，第 4 次约 10 分钟，第 5 次约 30 分钟，第 6 次约 2 小时，第 7 次约 8 小时，第 8 次约 24 小时。失败条件包括非 2XX 响应、超时（建议 5 秒内）和连接错误。
IP 白名单
Terra Webhook 来源 IP 列表为：18.133.218.210、18.169.82.189、18.132.162.19、18.130.218.186、13.43.183.154、3.11.208.36、35.214.201.105、35.214.230.71、35.214.252.53、35.214.229.114。可作为额外安全措施进行校验。
使用方式
- 在 Terra 控制台 → Destinations → Webhooks 添加 Webhook URL（生产环境必须为 HTTPS），复制签名密钥，并选择要接收的事件。
- 在服务端创建 POST 端点（示例路径
/webhooks/terra），先验证签名，再解析负载并异步处理，最后立即返回 200。 - 本地开发可使用 ngrok 暴露本地端口（如
ngrok http 5000），将 ngrok URL 填入 Terra 控制台。也可使用 curl 模拟请求，或使用 webhook.site 观察负载。
适用场景
适用于需要将 Terra 健康数据实时同步到自有系统的应用，例如健身追踪、睡眠分析、每日活动汇总、用户连接状态管理等。
限制
资料未提供 Terra API 的收费、价格、平台支持范围或性能指标等信息。示例代码为 Python（Flask + Celery），其他语言需自行适配。签名验证依赖从 Terra 控制台获取的签名密钥。