拓冰网站定制 
如何实时掌握用户健康数据Open Wearables Webhooks 完整配置与调试教程【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearablesOpen Wearables 是一个自托管的穿戴设备数据平台它将 Garmin、Oura、Apple Health 等设备的健康数据统一为一个 AI 友好的 API。本教程带你用 Webhooks 实时接收用户的心率、睡眠、运动等健康数据事件——无需轮询数据一到就推送并覆盖从启用、注册端点、签名验收到调试排查的完整流程。为什么用 Webhooks 而不是轮询传统做法是让服务器每隔几分钟调用一次拉取接口检查有没有新数据。而 Open Wearables 的 Outgoing Webhooks 会在每个新运动保存、每段睡眠入库、每批时序数据写入的瞬间向你的服务器发起一次 HTTP POST 推送。⚡实时性数据落库即触发没有轮询间隔带来的延迟零空转没有新数据就不打扰你的服务器完整载荷时序事件直接携带samples数组无需二次调用 API自动重试基于 Svix 投递失败事件按指数退避自动重发 注意自托管部署中 Webhooks默认关闭需要先启用才能收到事件。第一步启用 Outgoing Webhooks在后端.env中设置开关然后重启容器即可OUTGOING_WEBHOOKS_ENABLEDtrue配置项位置见 .env.example。如果你使用的是托管 PostgresAWS RDS / Railway需要确保应用数据库用户有权创建数据库或提前建好svix数据库——Svix 服务把它的表结构放在那里。启用状态的检查逻辑在 outgoing_webhooks.py 中未启用时 API 会明确返回 403 并提示你设置该环境变量。第二步注册一个 Webhook 端点有两种方式新手推荐从 Web 控制台入手对应源码 webhooks.tsx登录后进入Webhooks页面点击创建端点填入一个公网可达的 HTTPS 地址例如https://yourapp.com/webhooks/health可选填描述、事件过滤器和用户过滤器控制台表单 webhook-form.tsx 支持按事件分组勾选要订阅的事件类型。也可以用 API 完成同样的事需先用POST /api/v1/auth/login拿到 Bearer Tokencurl -X POST http://localhost:8000/api/v1/webhooks/endpoints \ -H Authorization: Bearer YOUR_JWT_TOKEN \ -H Content-Type: application/json \ -d { url: https://yourapp.com/webhooks/health, description: 生产环境健康数据处理器 }响应中会返回端点id形如ep_xxxx务必保存后续获取密钥、查看投递记录都要用它。第三步获取签名密钥Signing Secret每个端点都有一个独立的 HMAC 签名密钥用于验证推送确实来自 Open Wearablescurl http://localhost:8000/api/v1/webhooks/endpoints/ep_xxx/secret \ -H Authorization: Bearer YOUR_JWT_TOKEN响应形如{ key: whsec_... }。这个密钥请妥善保管在服务器环境变量里它是防伪造、防重放攻击的唯一凭证。理解推送载荷与签名验证每次投递是标准 JSON包含type事件名和data业务数据例如一段新睡眠{ type: sleep.created, data: { user_id: 550e8400-..., efficiency_percent: 87.0, stages: { deep_minutes: 95, rem_minutes: 80 }, source: { provider: oura, device: Oura Ring Gen3 } } }同时每个请求都带三个签名头请求头作用svix-id唯一消息 ID跨重试保持不变用于幂等去重svix-timestamp发送时间戳超过 5 分钟的旧消息会被 SDK 自动拒绝svix-signaturev1,base64_hmac签名的逗号分隔列表推荐的验证方式Python / Node 都有官方 SDK安装svix库后用Webhook(secret).verify(rawBody, headers)一步完成验签签名不对或时间戳过旧会抛异常此时应直接返回 400。先验签、再处理这是安全底线。事件类型全览能收到哪些健康数据事件命名遵循资源.动作约定完整清单可通过GET /api/v1/webhooks/event-types获取源码枚举见 event_types.py。会话类事件一次完整记录触发一次connection.created/connection.revoked— 用户连接或断开穿戴设备workout.created— 新的运动会话含卡路里、距离、平均心率sleep.created— 新的或合并后的睡眠会话含深睡/REM 分期menstrual_cycle.created— 新的月经周期记录时序类事件按批推送携带完整样本事件覆盖的指标heart_rate.created心率、静息心率、行走平均心率steps.created步数calories.created总能量、基础代谢spo2.created血氧饱和度、外周灌注指数body_temperature.created体温、皮肤温度blood_glucose.created血糖、酒精含量、胰岛素输送recovery_score.created恢复分、Garmin 身体电量时序事件比拉取接口更慷慨——每条samples数据点结构与GET /api/v1/users/{user_id}/timeseries完全一致消费端只维护一套 schema 即可。超过 2500 个样本的大批次会自动拆分为带chunk_index/total_chunks的分片事件方便你重组。过滤事件只订阅你要的数据按事件类型过滤注册或更新端点时传filter_types例如只关心运动和睡眠{ url: https://yourapp.com/hook, filter_types: [workout.created, sleep.created] }不传该字段则接收全部事件。想移除过滤时发送filter_types: []空列表才是清除null会保留原过滤。按用户过滤传user_id可以把端点限定为只接收某个用户的事件其他用户的数据在投递前就被丢弃。两个过滤条件可以叠加使用例如只接收某用户的运动事件。调试确认你的端点真的在收这是新手最容易卡住的环节Open Wearables 提供了三个调试利器发测试事件强烈推荐先做——不等待真实数据直接触发一个逼真样例载荷curl -X POST http://localhost:8000/api/v1/webhooks/endpoints/ep_xxx/test \ -H Authorization: Bearer YOUR_JWT_TOKEN \ -d { event_type: workout.created }查看投递历史——GET /api/v1/webhooks/endpoints/ep_xxx/attempts返回每一次投递的 HTTP 状态码和时间戳4xx/5xx 一目了然查看全部消息——GET /api/v1/webhooks/messages可看到所有已发送消息对应前端组件为投递记录表格 webhook-attempts-table.tsx 和测试事件对话框 webhook-test-event-dialog.tsx。常见故障速查症状排查方向什么都没收到确认OUTGOING_WEBHOOKS_ENABLEDtrue并已重启确认端点是公网 HTTPS收到但返回 400大概率验签失败——确认用的是原始请求体字节做 HMAC而非反序列化后的对象事件被重复处理用svix-id做幂等存储重试会携带同一 ID间歇性丢失检查 attempts 接口的状态码端点应快速返回 2xx重活丢进后台队列最佳实践清单✅ 验签通过后立即返回 2xx把重计算异步化——超时会被视为失败并重试✅ 用svix-id做幂等键重试安全✅ 即使是不感兴趣的事件也返回 2xx否则会被反复重投✅ 拉取 API 始终可用用作补数、对账或丢失恢复️ 数据入库永不因 Webhook 故障而阻塞——投递失败只会排队重试实现见 events.py进阶阅读完整 API 参考与载荷字段说明webhooks.mdxSvix 投递服务封装svix.pyWebhook 事件触发助手函数events.py开发者门户中的 Webhooks 页面前端路由 webhooks.tsx照着以上步骤走完你的应用就能在用户每跑完一次步、每睡完一晚的几分钟内收到推送——这才是实时健康数据应有的样子 【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何实时掌握用户健康数据：Open Wearables Webhooks 完整配置与调试教程
如何实时掌握用户健康数据Open Wearables Webhooks 完整配置与调试教程【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearablesOpen Wearables 是一个自托管的穿戴设备数据平台它将 Garmin、Oura、Apple Health 等设备的健康数据统一为一个 AI 友好的 API。本教程带你用 Webhooks 实时接收用户的心率、睡眠、运动等健康数据事件——无需轮询数据一到就推送并覆盖从启用、注册端点、签名验收到调试排查的完整流程。为什么用 Webhooks 而不是轮询传统做法是让服务器每隔几分钟调用一次拉取接口检查有没有新数据。而 Open Wearables 的 Outgoing Webhooks 会在每个新运动保存、每段睡眠入库、每批时序数据写入的瞬间向你的服务器发起一次 HTTP POST 推送。⚡实时性数据落库即触发没有轮询间隔带来的延迟零空转没有新数据就不打扰你的服务器完整载荷时序事件直接携带samples数组无需二次调用 API自动重试基于 Svix 投递失败事件按指数退避自动重发 注意自托管部署中 Webhooks默认关闭需要先启用才能收到事件。第一步启用 Outgoing Webhooks在后端.env中设置开关然后重启容器即可OUTGOING_WEBHOOKS_ENABLEDtrue配置项位置见 .env.example。如果你使用的是托管 PostgresAWS RDS / Railway需要确保应用数据库用户有权创建数据库或提前建好svix数据库——Svix 服务把它的表结构放在那里。启用状态的检查逻辑在 outgoing_webhooks.py 中未启用时 API 会明确返回 403 并提示你设置该环境变量。第二步注册一个 Webhook 端点有两种方式新手推荐从 Web 控制台入手对应源码 webhooks.tsx登录后进入Webhooks页面点击创建端点填入一个公网可达的 HTTPS 地址例如https://yourapp.com/webhooks/health可选填描述、事件过滤器和用户过滤器控制台表单 webhook-form.tsx 支持按事件分组勾选要订阅的事件类型。也可以用 API 完成同样的事需先用POST /api/v1/auth/login拿到 Bearer Tokencurl -X POST http://localhost:8000/api/v1/webhooks/endpoints \ -H Authorization: Bearer YOUR_JWT_TOKEN \ -H Content-Type: application/json \ -d { url: https://yourapp.com/webhooks/health, description: 生产环境健康数据处理器 }响应中会返回端点id形如ep_xxxx务必保存后续获取密钥、查看投递记录都要用它。第三步获取签名密钥Signing Secret每个端点都有一个独立的 HMAC 签名密钥用于验证推送确实来自 Open Wearablescurl http://localhost:8000/api/v1/webhooks/endpoints/ep_xxx/secret \ -H Authorization: Bearer YOUR_JWT_TOKEN响应形如{ key: whsec_... }。这个密钥请妥善保管在服务器环境变量里它是防伪造、防重放攻击的唯一凭证。理解推送载荷与签名验证每次投递是标准 JSON包含type事件名和data业务数据例如一段新睡眠{ type: sleep.created, data: { user_id: 550e8400-..., efficiency_percent: 87.0, stages: { deep_minutes: 95, rem_minutes: 80 }, source: { provider: oura, device: Oura Ring Gen3 } } }同时每个请求都带三个签名头请求头作用svix-id唯一消息 ID跨重试保持不变用于幂等去重svix-timestamp发送时间戳超过 5 分钟的旧消息会被 SDK 自动拒绝svix-signaturev1,base64_hmac签名的逗号分隔列表推荐的验证方式Python / Node 都有官方 SDK安装svix库后用Webhook(secret).verify(rawBody, headers)一步完成验签签名不对或时间戳过旧会抛异常此时应直接返回 400。先验签、再处理这是安全底线。事件类型全览能收到哪些健康数据事件命名遵循资源.动作约定完整清单可通过GET /api/v1/webhooks/event-types获取源码枚举见 event_types.py。会话类事件一次完整记录触发一次connection.created/connection.revoked— 用户连接或断开穿戴设备workout.created— 新的运动会话含卡路里、距离、平均心率sleep.created— 新的或合并后的睡眠会话含深睡/REM 分期menstrual_cycle.created— 新的月经周期记录时序类事件按批推送携带完整样本事件覆盖的指标heart_rate.created心率、静息心率、行走平均心率steps.created步数calories.created总能量、基础代谢spo2.created血氧饱和度、外周灌注指数body_temperature.created体温、皮肤温度blood_glucose.created血糖、酒精含量、胰岛素输送recovery_score.created恢复分、Garmin 身体电量时序事件比拉取接口更慷慨——每条samples数据点结构与GET /api/v1/users/{user_id}/timeseries完全一致消费端只维护一套 schema 即可。超过 2500 个样本的大批次会自动拆分为带chunk_index/total_chunks的分片事件方便你重组。过滤事件只订阅你要的数据按事件类型过滤注册或更新端点时传filter_types例如只关心运动和睡眠{ url: https://yourapp.com/hook, filter_types: [workout.created, sleep.created] }不传该字段则接收全部事件。想移除过滤时发送filter_types: []空列表才是清除null会保留原过滤。按用户过滤传user_id可以把端点限定为只接收某个用户的事件其他用户的数据在投递前就被丢弃。两个过滤条件可以叠加使用例如只接收某用户的运动事件。调试确认你的端点真的在收这是新手最容易卡住的环节Open Wearables 提供了三个调试利器发测试事件强烈推荐先做——不等待真实数据直接触发一个逼真样例载荷curl -X POST http://localhost:8000/api/v1/webhooks/endpoints/ep_xxx/test \ -H Authorization: Bearer YOUR_JWT_TOKEN \ -d { event_type: workout.created }查看投递历史——GET /api/v1/webhooks/endpoints/ep_xxx/attempts返回每一次投递的 HTTP 状态码和时间戳4xx/5xx 一目了然查看全部消息——GET /api/v1/webhooks/messages可看到所有已发送消息对应前端组件为投递记录表格 webhook-attempts-table.tsx 和测试事件对话框 webhook-test-event-dialog.tsx。常见故障速查症状排查方向什么都没收到确认OUTGOING_WEBHOOKS_ENABLEDtrue并已重启确认端点是公网 HTTPS收到但返回 400大概率验签失败——确认用的是原始请求体字节做 HMAC而非反序列化后的对象事件被重复处理用svix-id做幂等存储重试会携带同一 ID间歇性丢失检查 attempts 接口的状态码端点应快速返回 2xx重活丢进后台队列最佳实践清单✅ 验签通过后立即返回 2xx把重计算异步化——超时会被视为失败并重试✅ 用svix-id做幂等键重试安全✅ 即使是不感兴趣的事件也返回 2xx否则会被反复重投✅ 拉取 API 始终可用用作补数、对账或丢失恢复️ 数据入库永不因 Webhook 故障而阻塞——投递失败只会排队重试实现见 events.py进阶阅读完整 API 参考与载荷字段说明webhooks.mdxSvix 投递服务封装svix.pyWebhook 事件触发助手函数events.py开发者门户中的 Webhooks 页面前端路由 webhooks.tsx照着以上步骤走完你的应用就能在用户每跑完一次步、每睡完一晚的几分钟内收到推送——这才是实时健康数据应有的样子 【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考