SuperAPI AI 工具集

oura-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:用于在服务端搭建 Oura Webhook 处理器,接收并验证 Oura Ring 推送的事件。Oura 在同一回调地址上有两类请求:订阅握手(GET)和事件投递(POST)。

主要能力:

  1. 订阅握手:创建订阅时 Oura 向 callback_url 发送带 verification_token 和 challenge 查询参数的 GET,校验 token 后返回 200 与 JSON {"challenge": "<value>"}。
  2. 事件验证:POST 请求携带 x-oura-signature 与 x-oura-timestamp,使用 HMAC-SHA256,以 client secret 为密钥,对 timestamp + 原始请求体计算十六进制摘要并转为大写,再用定时安全比较与签名比对。必须使用原始请求体,而非重新序列化已解析的 payload。
  3. 事件分发:事件载荷较精简,包含 event_type、data_type、object_id、event_time、user_id,可用 object_id 调 Oura API 获取完整记录。

常用 data_type 包括 sleep、daily_sleep、daily_readiness、daily_activity、workout、session、daily_stress 等,完整枚举共 17 项;每个订阅为一个 data_type 与 event_type(create、update、delete)的组合。

环境变量:OURA_CLIENT_SECRET(签名密钥)、OURA_VERIFICATION_TOKEN(订阅时自设)、OURA_CLIENT_ID(仅管理订阅时需要)。

本地开发可运行:npx hookdeck-cli listen 3000 oura --path /webhooks/oura

限制与注意:Oura 会重试最多 10 次,建议确保幂等处理;签名验证要求长度一致,否则返回 false。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/,更多细节见 references/overview.md、setup.md、verification.md。