Webhook 事件
开放平台在关键业务事件发生时，向合作方配置的 Webhook URL 推送实时通知。 合作方无需轮询，即可第一时间感知用户行为变化。
Webhook HTTP 投递服务正在开发中，预计近期上线。以下为规格预览，接口和事件格式在正式发布前可能调整。
概述
Webhook 采用 HTTP POST 方式推送，请求体为 JSON 格式。 平台期望合作方服务在 5 秒内返回 HTTP 200， 否则视为推送失败并触发重试。
配置 Webhook
在控制台「应用管理 → Webhook 设置」中配置：
- Endpoint URL：接收推送的 HTTPS 地址（需支持 TLS 1.2+）
- 订阅事件：选择需要接收的事件类型
- 签名密钥：平台自动生成，用于验证推送来源
事件列表
| 事件名 | 触发时机 |
|---|---|
user.profile.updated | 用户基础信息变更（PATCH 接口调用成功） |
user.family_group.created | 家庭组新增或更新 |
user.family_group.deleted | 家庭组解散（组内成员已级联软删） |
user.family_member.created | 家庭成员新增 |
user.family_member.updated | 家庭成员信息更新 |
user.family_member.deleted | 家庭成员删除 |
health.station.appointment.confirmed | 预约成功 |
health.station.appointment.cancelled | 预约取消 |
health.station.checkin.completed | 用户到站核验成功，检测开始 |
health.daily_report.completed | 健康日报 AI 解读完成 |
benefit_card.activated | 权益卡激活 |
benefit_card.exhausted | 权益卡次数耗尽 |
请求体格式
{
"event": "health.daily_report.completed",
"event_id": "evt_xxxxxxxxxxxx", // 全局唯一事件 ID，可用于幂等处理
"app_id": "100023",
"timestamp": "2026-04-01T10:30:00+08:00",
"data": {
// 事件相关业务数据，因事件类型而异
"report_no": "DR20260401001",
"open_user_id": 10086,
"family_member_id": 3001,
"ai_status": "completed"
}
}签名验证
平台在每次推送时附带 X-Webhook-Signature Header， 用于验证请求来自晓葆平台（防止伪造）：
X-Webhook-Signature: sha256=<hmac_sha256_hex>验证方式：
// PHP 示例
$body = file_get_contents("php://input");
$sigHeader = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? "";
$expected = "sha256=" . hash_hmac("sha256", $body, $webhookSecret);
if (!hash_equals($expected, $sigHeader)) {
http_response_code(401);
exit("Signature mismatch");
}必须使用
hash_equals（时间恒定比较）而非 === 进行签名比对， 防止时序攻击。重试机制
- 合作方服务需在 5 秒内返回 HTTP
2xx，否则视为失败 - 失败后按指数退避重试：5s → 30s → 2min → 10min → 30min，共 5 次
- 5 次全部失败后标记为死信，可在控制台手动重新投递
- 合作方应使用
event_id做幂等处理，避免重试导致重复执行
即将上线
- Webhook 调试工具（控制台内直接测试推送）
- 事件日志查询（按时间/事件类型查询历史推送记录）
- 手动重推（针对死信事件）