定义
Webhook 当设备上线/离线、告警触发、OTA 完成等事件发生时，平台向用户配置的 URL 发起 HTTP POST 请求，推送事件数据。用于与 ITSM、Work Order、自建系统集成，由 Rule Engine 触发。
配置与安全
Webhook 需配置目标 URL、请求方法（通常 POST）、可选请求头（如签名、认证 Token）。支持 HMAC 签名验证，接收方可根据签名校验请求来源。建议使用 HTTPS、配置重试策略（如指数退避）、设置超时，确保推送可靠性。失败时可记录日志、告警或进入死信队列供人工处理。
事件类型
常见事件包括：设备上线/离线、属性变更、事件上报、告警触发、OTA 任务状态变更、设备注册/删除等。Webhook payload 通常包含事件类型、时间戳、设备标识、关联数据。接收方可解析 payload 后创建 Work Order 工单、同步至 ITSM、触发业务逻辑或写入数据仓库。
与 OpenAPI 对比
Webhook 为服务端主动推送，适合实时事件驱动；OpenAPI 为客户端主动拉取，适合批量查询与配置。两者互补，Webhook 负责事件通知，OpenAPI 负责数据获取与操作，共同构成平台开放能力。
推送是至少一次的事件通知
事件推送解决的是“有事发生时通知对方”，不是给对方一份可以当数据库用的全量档案。平台在约定的事件上向接收地址发出请求，内容里带事件标识、类型、发生时刻和相关设备。网络超时、对方短暂失败时，平台会按策略重试，所以同一事件可能到达多次。这是至少一次，不是恰好一次。接收方若没有去重，一次告警会变成多张单据。
推送不保证顺序在所有事件之间都被严格保持，尤其经过重试之后，后发生的事件可能先被成功接收。接收方应按事件里的时刻和标识自行排序，不能假设后到达的一定更新。载荷里放标识和摘要，体积大的历史曲线让对方再通过接口按标识拉取。把整段遥测塞进每一次推送，失败重试时会放大流量，也会让签名和超时都变得不稳定。
接收方必须能按事件标识去重
使用条件是接收方保存最近一段时间见过的事件标识，重复到达时直接返回已经处理过，而不再执行业务。标识由平台生成并在重试中保持不变。接收方自己用到达时间制造标识，则无法把重试认成同一件事。去重记录的保存时间应长于平台的最大重试窗口，否则窗口后半段的重试会被当成新事件。
签名校验要在解析业务之前完成。共享密钥或公钥按平台文档验证请求体未被篡改，校验失败直接拒绝，不进入重试所依赖的成功路径。地址必须是接收方控制的接入点，并使用加密传输。平台侧应能停用某个订阅、查看最近的响应码，但不能把对方的内网地址写死在无法轮换的配置里。需要留痕时把每次尝试的结果写入审计日志，包括失败原因，而不是只在最终成功时记一条。
在处理完成前就返回成功
接收方若一收到请求就返回成功，再在后台慢慢写工单，后台失败时平台认为已经送达，不会再试。成功响应应表示“这个事件标识已经耐久地记下，后续即使进程重启也能继续处理”。处理本身可以异步，但记下这一步必须先完成。返回过慢则会触发平台超时重试，与去重配合才能安全：第一次其实已记下，第二次被识别为重复。
用推送去直接驱动不可重复的现场动作，同样危险。重试或多订阅会导致动作执行多次。推送只负责通知，现场动作由带指令标识的控制路径执行。订阅过宽是另一个常见问题：把所有属性变化都推出去，接收方会被周期遥测淹没，真正的告警埋在里面。订阅应限定事件类型和设备范围，并在接收方做不了处理时主动缩小，而不是把失败请求无限堆进平台重试队列。对方长期失败要进入死信并告警给订阅者，不能无声丢弃，也不能无上限地重试下去占满发送容量。
订阅配置里写明重试次数、间隔和最后一次失败后进入死信的条件。死信要能按事件标识重放，重放仍使用原来的标识，接收方的去重才继续有效。若重放生成新标识，对方会再执行一次业务。发送侧记录每次响应的状态码和耗时，但不要记录完整的密钥或签名材料。接收地址变更时先用测试事件验证新地址，再把生产订阅切过去，旧地址保留到在途重试结束。突然删除旧地址会使已发出的重试全部失败并灌满死信。测试事件与生产事件使用不同的类型标记，接收方看到测试标记时只做连通性记录，不创建正式单据，也不计入去重后的业务计数。