一、场景概述
API 开放对接 以企业主动拉取为主，而大量业务（卡状态变更、支付成功、流量预警触发）更适合平台主动推送。Webhook 与事件订阅在达希物联网云平台中提供「事件驱动」集成：企业注册 HTTPS 端点，订阅关心的事件类型；当事件发生时，平台按约定 JSON 格式 POST 请求，附带签名防篡改；接收失败时指数退避重试，多次失败后进入死信队列供人工处理。
参考 Stripe、阿里云与主流 IoT 平台实践：事件应幂等（带唯一 event_id）；支持至少一次投递语义；客户端应返回 2xx 表示成功。与 沙箱与调用日志 联动，便于联调与排障。
二、核心能力
事件目录
覆盖卡生命周期、套餐变更、流量阈值、订单支付、退款、分账结果等；每类事件附带 schema 与示例，便于企业生成解析代码。
过滤与路由
按项目、客户、ICCID 前缀过滤事件；多环境（开发/生产）分离 endpoint；支持同一事件多订阅方（如 ERP 与 CRM 各收一份）。
安全
时间戳防重放；IP 白名单；可选 mTLS；密钥轮换与版本化签名算法。
可观测
投递成功率、延迟、失败原因统计；支持按事件 ID 查询单条投递记录与重放。
三、与 API 的关系
Webhook 与 REST API 互补：查询类、低频操作用 API；状态变更通知用 Webhook 降低轮询压力。与 消息通知与触达 面向终端用户不同，Webhook 面向企业系统。
四、典型应用场景
- 卡状态变更实时通知客户：运营商侧批量停机后，平台通过Webhook将受影响卡的状态变更事件推送至企业CRM系统，CRM自动触发短信通知终端用户，实现端到端的实时告知闭环。
- 支付成功自动开卡：用户完成在线支付后，平台推送order.paid事件至企业后台，后台立即调用开卡API并将结果回写用户账户，全程自动化无需轮询，将开卡延迟从分钟级降至秒级。
- 流量预警联动自动补包：设备流量消耗接近阈值时，Webhook推送traffic.alert事件至企业运营系统，系统自动为该设备购买加油包并通知设备管理员，实现流量保障的自动化闭环。
五、实施建议
企业端应实现快速 200 响应，业务处理异步化；使用队列削峰。上线前用沙箱模拟各类事件。监控5xx 与超时比例。
六、方案价值
通过 Webhook 与事件订阅，达希物联网云平台帮助客户构建实时、低延迟的集成架构，提升自动化水平与用户体验。事件驱动架构取代主动轮询后，企业系统的API调用量大幅降低，同时将状态变更的感知延迟从分钟级压缩至秒级；HMAC签名与时间戳防重放机制确保每条推送都经过安全验证，防止伪造事件导致的误操作；死信队列与重放功能保障了即使在网络异常时事件也不会丢失，满足金融与政企场景对消息可靠性的严格要求。