1. Webhooks 概述
Webhooks 是慧医云提供的实时事件推送机制。当系统中的关键业务事件发生时（如订单状态变更、库存告警、证照到期），系统会自动向您配置的回调 URL 发送 HTTP POST 请求，推送事件数据。
相比轮询方式，Webhooks 具有实时性高、资源消耗低的优势，是实现系统间自动化协同的最佳方式。
2. 支持的事件类型
| 事件类型 | eventType | 触发时机 | 推送频率 |
|---|---|---|---|
| 订单状态变更 | order.status_changed | 订单状态发生变化时 | 实时 |
| 入库完成 | inventory.inbound_completed | 采购入库验收通过后 | 实时 |
| 出库完成 | inventory.outbound_completed | 销售出库复核通过后 | 实时 |
| 库存告警 | inventory.low_stock | 库存低于安全库存线 | 每产品每天最多1次 |
| 效期预警 | expiry.warning | 产品进入近效期预警区间 | 每批号每天最多1次 |
| 证照到期 | certificate.expiring | 供应商/产品证照即将到期 | 到期前30/15/7天各1次 |
| 温湿度异常 | environment.alert | 温湿度超出设定阈值 | 实时 |
3. 配置步骤
1
准备回调 URL
在您的服务器上开发一个接收 POST 请求的接口，确保 URL 支持 HTTPS 协议且可公网访问。
2
注册 Webhook
在慧医云控制台"系统设置→Webhooks"中添加新配置：填写回调 URL、选择订阅的事件类型、设置密钥（用于签名验证）。
3
验证签名
收到推送后，使用 HMAC-SHA256 算法验证 X-YLT-Signature 请求头中的签名，防止伪造推送。
4
返回确认
收到推送后应在 5 秒内返回 HTTP 200。若超时或返回非 2xx 状态码，系统会重试最多 3 次（间隔 1 分钟、5 分钟、15 分钟）。
4. 推送数据格式示例
// 订单状态变更回调示例
POST https://your-server.com/api/webhook/ylt
Content-Type: application/json
X-YLT-Event: order.status_changed
X-YLT-Signature: sha256=abc123def456...
{
"eventId": "evt_20240520_001",
"eventType": "order.status_changed",
"timestamp": "2024-05-20T14:30:00Z",
"data": {
"orderId": "SO20240520001",
"previousStatus": "pending_approval",
"currentStatus": "approved",
"changedBy": "admin@hospital-a.com",
"changedAt": "2024-05-20T14:29:55Z"
}
}⚠️
注意
回调 URL 必须返回 HTTP 2xx 状态码。连续 10 次推送失败后，该 Webhook 配置将被自动禁用并发送邮件通知管理员。