Webhooks

Webhook（网络钩子） 将 dAio 与您自己的系统连接起来。您无需持续轮询平台，而是让 dAio 主动通知您：一旦发生事件 —— 触发了一条天气警报、检测到一项高风险 —— dAio 便会实时向您选择的端点发送一个已签名的 HTTP 请求。由此您可以自动化各类工作流程：开具工单、内部通知、更新业务仪表盘，或启动现场行动计划。

它是 dAio 的警报与您的信息系统之间的桥梁。

已配置的 Webhook 列表

提示 : 请从订阅单一事件类型的单个 Webhook 开始，端到端地验证整条链路，然后再行扩展。这样可以避免在使处理变得可靠之前，就用通知淹没您的系统。

配置 Webhook

进入 设置 > Webhooks。
点击 新建 Webhook。
填写目标 URL：您服务器的 HTTPS 端点（例如 https://votre-serveur.com/webhook）。
通过点击相应的标签，选择要监听的事件。
点击创建确认。

创建时会自动生成一个密钥。它用于以 HMAC-SHA256 对每个请求进行签名（见下文）：请将其保存在服务器端，它使您能够验证每次调用确实来自 dAio。

注意 : URL 必须为 HTTPS 且可公开访问。使用普通 HTTP 的端点，或位于关闭的防火墙之后的端点，将无法接收投递。

可用事件

事件	说明
`weather.alert`	某个站点触发了一条天气警报
`weather.threshold`	越过了一个自定义天气阈值
`air_quality.alert`	发布了一条空气质量警报
`pollen.alert`	发布了一条花粉警报
`marine.alert`	发布了一条海洋状况警报
`frost.alert`	触发了一条霜冻警报
`storm.alert`	触发了一条雷暴／风暴警报
`business.risk_high`	针对您的业务活动检测到了高风险等级

提示 : 每个 Webhook 只订阅接收系统实际使用的事件。一个「工单」端点不需要接收与「仪表盘」端点相同的事件。

负载（payload）格式

每次投递都是一个 POST 请求，其请求体是一个 JSON 对象。整体结构如下：

json

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

event 字段标识事件类型，timestamp 表示发布时间（UTC，ISO 8601 格式），data 包含事件特有的详细信息。

HMAC-SHA256 认证

每个请求都使用您的密钥通过 HMAC-SHA256 进行签名。签名通过 X-Daio-Signature 头传递，格式为 sha256=<signature>。

在处理请求之前，请务必验证此签名：正是它保证了该调用来自 dAio，且负载未被篡改。

服务器端验证（Python）：

python

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

注意 : 请在任何 JSON 反序列化之前，对请求的原始请求体（收到的字节）计算签名。哪怕最细微的重新格式化都会改变哈希值，导致验证失败。

测试与调试

点击 Webhook 旁的测试图标（▶），向您的端点发送一个虚拟事件。
HTTP 2xx 响应确认您的服务器已收到并接受该请求。
展开该 Webhook 即可查看其最近的投递：HTTP 代码、事件类型和时间戳。
一个彩色圆点指示 Webhook 的状态：绿色 = 启用，红色 = 因反复失败而被禁用。

投递历史

每次发送都会被记录。展开某个 Webhook，即可查看每次尝试的：

响应的 HTTP 代码（小于 300 为绿色，否则为红色）
已投递的事件类型
尝试的日期与时间

当投递发生失败时，Webhook 上会显示一个失败计数器。

重试与可靠性

dAio 在失败时会以递增的间隔自动重试投递。因此，您的端点必须是幂等的：同一次投递可能会到达多次，而您的处理必须在没有副作用的情况下产生相同的结果。

注意 : 您的端点必须在 10 秒内以 HTTP 2xx 代码作出响应。超过该时限，或出现错误代码时，投递将被视为失败并会被重试。在反复失败之后，Webhook 会被自动禁用。

最佳实践

始终先验证 HMAC 签名，再处理负载：切勿信任未经认证的请求。
快速响应：立即返回 200，然后在后台处理工作负载。您可以避免超时和不必要的重试。
使您的处理幂等，以便安全地吸收多次投递。
在源头进行过滤：每个 Webhook 只订阅对其接收系统有用的事件。
监控失败计数器和投递历史，以便在端点被禁用之前迅速发现故障。
在您这边每次发生变更（部署、URL 变更）后，使用「测试」按钮来验证整条链路，而无需等待真实事件。

提示 : 将您的 Webhook 与警报以及您的团队配置相结合，从而自动将正确的信息路由到正确的系统。Webhook 的可用性取决于您的订阅。

Webhooks ​

配置 Webhook ​

可用事件 ​

负载（payload）格式 ​

HMAC-SHA256 认证 ​

测试与调试 ​

投递历史 ​

重试与可靠性 ​

最佳实践 ​