Webhook

插件用途

将变量、设备、报警和插件事件发送到钉钉自定义机器人、企业微信消息推送（原群机器人）或自定义 HTTP 接口。平台类型是必选协议边界，系统会据此生成厂商消息体、执行钉钉加签并校验平台业务响应。

转发组范围、触发、分批、缓存和启停见数据转发。本页只说明 Webhook 请求、接口模板、上传模板和专用调试。

功能入口

进入“开发配置 → 数据转发”，按以下顺序配置：

1. 新增或编辑转发组，先保存变量范围、触发模式、定时间隔、在线过滤和批处理策略。
2. 新增目标，选择“Webhook”，填写目标名称、启用状态、日志级别和启动超时。
3. 打开“目标属性”，配置请求地址、消息格式、认证、模板、脚本和缓存。
4. 保存并启用转发组和目标，确认目标在线，再使用“目标调试”执行只读探测或测试请求。

目标基本信息

参数	默认值	如何配置
所属转发组	-	必须选择已保存的转发组；目标只接收该组范围内的变量。
目标名称	-	必填，同一转发组内不能重复。建议包含接口用途和环境。
启用	开启	关闭时 Webhook 目标不会发送请求。
日志级别	Info	排查 HTTP、签名或模板问题时临时使用 Debug，完成后恢复。
启动超时	60 秒	页面可填 1～3600 秒。

目标属性

消息与接口

参数	默认值	如何配置
Webhook平台	Custom	从枚举下拉框选择：DingTalk 表示钉钉自定义机器人；WeCom 表示企业微信消息推送；Custom 表示普通 HTTP 接口。必须按实际接收端选择，系统不会根据 URL 自动猜测。
消息格式	Raw	DingTalk、WeCom 可选 Text 或 Markdown，系统按平台包装；两者也可用 Raw 发送上传模板生成的完整厂商 JSON。Custom 必须使用 Raw。
设备Topic模板	空	设备请求 URL。留空则不发送设备模型；可使用 ${字段名}。
变量Topic模板	http://127.0.0.1:7502/ThingsGateway/Variable	变量请求 URL。可使用 ${DeviceName}、${Name} 等字段按设备或变量分组。
报警Topic模板	空	报警请求 URL。留空则不发送报警模型。
插件事件Topic模板	空	插件事件请求 URL。留空则不发送插件事件模型。
请求超时(秒)	10	单次 HTTP POST 最大等待时间，填写正整数。

Topic 模板在 Webhook 中实际表示 HTTP/HTTPS 请求 URL，不是 MQTT Topic。${字段名} 必须存在于对应实体或实体脚本结果中。

安全认证

参数	默认值	如何配置
签名密钥	空	仅 DingTalk 且机器人启用“加签”安全设置时填写以 SEC 开头的 Secret。发送时系统在 URL 追加 timestamp 和 sign；WeCom、Custom 必须留空。
自定义请求头	空	填 JSON 对象，例如 {"Authorization":"Bearer <token>","X-Environment":"test"}。必须是字符串到字符串的 JSON 字典；格式错误会使本次发送失败。

签名密钥、钉钉 URL 中的 access_token、企业微信 URL 中的 key 和自定义请求头值都属于敏感配置，不要放入模板、截图、工单或公开仓库。运行日志只显示不含查询参数的端点；签名不会替代 URL 中的 access_token。

钉钉自定义机器人

配置步骤

1. 在钉钉群中添加自定义机器人，复制完整 Webhook 地址，地址格式为 https://oapi.dingtalk.com/robot/send?access_token=<机器人Token>。
2. 将“Webhook平台”设为 DingTalk，把完整地址填入需要上传的数据 Topic 模板。
3. 机器人选择“加签”安全设置时，将以 SEC 开头的密钥填入“签名密钥”；使用关键词或 IP 白名单时留空。
4. 选择 Text、Markdown 或 Raw，保存后使用“发送测试请求”验证。

Text 会把上传模板结果作为文本内容：

{
  "msgtype": "text",
  "text": {
    "content": "上传模板生成的文本"
  }
}

Markdown 会生成钉钉要求的 title 和 text：

{
  "msgtype": "markdown",
  "markdown": {
    "title": "ThingsGateway",
    "text": "上传模板生成的 Markdown"
  }
}

使用 Raw 时，上传模板必须生成包含 msgtype 及对应消息对象的完整 JSON，可用于 at、link、actionCard、feedCard 等高级结构。

加签与成功判定

系统按钉钉官方规则使用当前 Unix 毫秒时间戳和 Secret 组成 timestamp + "\n" + secret，计算 HmacSHA256，执行 Base64 和 URL 编码，再把同一 timestamp 与 sign 追加到 URL。网关系统时间与钉钉请求时间误差不能超过 1 小时；应先在“系统设置”中配置可用 NTP。

钉钉即使拒绝消息也可能返回 HTTP 200。系统只有在 HTTP 为 2xx 且响应 JSON 的 errcode 为数字 0 或钉钉官方成功示例中的数字字符串 "0" 时才判定成功；其它值会让目标发送失败，并按“启用失败重试缓存”配置进入 CacheDB 重试。

每个钉钉机器人每分钟最多发送 20 条，超过后会限流 10 分钟。监控报警应启用列表上传或在上传模板中聚合为摘要，且“并发上传数量”保持 1。

企业微信消息推送

配置步骤

1. 在企业微信群中创建消息推送，复制完整 Webhook 地址，地址格式为 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<消息推送Key>。
2. 将“Webhook平台”设为 WeCom，把完整地址填入需要上传的数据 Topic 模板。
3. “签名密钥”必须留空。企业微信凭据已经包含在 URL 的 key 查询参数中。
4. 选择 Text、Markdown 或 Raw，保存后使用“发送测试请求”验证。

Text 的最小结构与钉钉相同。需要提醒成员时使用 Raw，在 text 中增加 mentioned_list 或 mentioned_mobile_list。

Markdown 与钉钉不同，企业微信只接受 content：

{
  "msgtype": "markdown",
  "markdown": {
    "content": "上传模板生成的 Markdown"
  }
}

企业微信文本内容最长 2048 字节，Markdown 内容最长 4096 字节，均使用 UTF-8。每个消息推送每分钟不能超过 20 条。使用 Raw 可发送 markdown_v2、图片、图文、文件、语音和模板卡片，但请求体必须完整符合企业微信文档；文件或语音还需先调用企业微信上传接口取得 media_id，本插件不会代替该上传步骤。

企业微信同样使用 HTTP 200 加 JSON errcode 表示业务结果。系统只有在 HTTP 为 2xx 且 errcode 可解析为整数 0 时判定成功；无效 key、频率限制、正文超限等响应会作为失败进入现有重试与日志链路。

自定义 HTTP 接口

“Webhook平台”选择 Custom 时必须选择 Raw，并在上传模板中生成接收端要求的完整 JSON。认证使用“自定义请求头”或 URL 自身参数，“签名密钥”必须留空。自定义平台没有统一业务响应契约，因此系统只以 HTTP 2xx 判定发送成功，不解析响应 JSON 中的业务字段。

目标变量属性

Webhook 提供通用的 数据1 至 数据10 十个可选文本字段，默认为空。它们不会自动加入 HTTP 正文；变量是否进入目标、别名、触发和分批仍在数据转发中配置。

参数	默认值	如何配置
数据1～数据10	空	按项目约定保存附加文本；要发送这些值时，必须在实体脚本或上传模板中显式引用。不要放入 Token、密钥或密码。

数据与脚本

参数	默认值	如何配置
详细日志	关闭	开启后记录请求内容或计数，短时间排查使用；生产环境保持关闭。
JSON缩进格式化	开启	关闭可减少请求正文大小。
JSON忽略Null	开启	关闭后保留 JSON 中的 null 字段。
设备列表上传	开启	设备数据按列表发送；关闭则逐条 POST。
变量列表上传	开启	变量数据按列表发送；关闭则逐条 POST。
变量字典上传	关闭	仅变量列表开启时生效，按 DeviceName → Name → Value 组织。
报警列表上传	开启	报警数据按列表发送；关闭则逐条 POST。
报警字典上传	关闭	仅报警列表开启时生效，按设备和变量组织。
插件事件列表上传	开启	插件事件按列表发送；关闭则逐条 POST。
设备/变量/报警/插件事件实体脚本	空	从表达式选择器选择对应脚本，脚本输出再参与 URL 分组和正文渲染。

上传模板字段

在“上传模板配置”中分别为设备、变量、报警和插件事件选择 Text 或 Json 模式并插入 ${字段名}，保存前先执行预览；正文模板留空时使用默认 JSON 序列化。

数据类型	可用字段
变量	Id、Name、DeviceName、Value、RawValue、LastSetValue、CollectGroup、CollectTime、CreateTime、ChangeTime、IsOnline、DataType、Unit、RegisterAddress、OtherMethod、Description、ProtectType、RpcWriteEnable、Remark1～Remark5、ValueInited、IsMemory
设备	Id、Name、ActiveTime、DeviceStatus、PluginName、Description、LastErrorMessage、Remark1～Remark5
报警	AlarmId、VariableId、Name、DeviceName、AlarmCode、AlarmLevel、AlarmLimit、AlarmText、RecoveryCode、AlarmTime、EventTime、FinishTime、ConfirmTime、ConfirmText、AlarmType、EventType、Remark1～Remark5
插件事件	DeviceName、ObjectValue

实体脚本会先改变上传对象，再参与接口分组和模板渲染；占位符必须与脚本输出一致。对应 URL 模板留空时，该类数据不会发送。

缓存与容量

参数	默认值	如何配置
启用失败重试缓存	开启	建议保持开启，请求失败时保留数据，服务恢复后自动补发。
缓存文件最大行数	262144	CacheDB 出站记录上限，超过后删除最旧数据。
上传分片大小	2000	每次从缓存取出的最大记录数；接收端限流时减小。
内存队列上限	100000	内存缓冲上限，超过后优先转入 CacheDB，持续超限仍可能丢弃旧数据。
过滤离线数据	关闭	开启后目标出队时过滤离线变量；转发组在线过滤也会生效。
并发上传数量	1	钉钉和企业微信均保持 1，并通过转发组批处理、定时间隔和列表上传控制在每分钟 20 条以内；自定义接口确认容量后再提高。

目标调试

进入“开发配置 → 数据转发”，选择 Webhook 目标，打开“调试 → 协议调试 · HttpWebhook”。

功能	作用
HTTP Webhook 调试	使用“探测”执行 DNS 与 HTTP HEAD 只读检查；使用“发送测试请求”向当前变量 URL 发送有界测试正文并查看状态码、耗时和响应摘要。

“发送测试请求”最多发送 64 KiB，且会弹出二次确认。测试正文仍会按当前“Webhook平台”和“消息格式”处理：Raw 原样发送，Text 或 Markdown 按厂商结构包装。日常调试不要调用生产写入或删除接口，应使用专用测试群或专用测试 URL；“探测”不会发送业务载荷。

验证方法

1. 明确选择 DingTalk、WeCom 或 Custom，再配置测试接口、认证和消息格式。
2. 在模板预览中检查 URL 和正文。
3. 发送一个测试变量或事件。
4. 在接收端核对实际消息；钉钉或企业微信测试结果必须同时满足 HTTP 2xx 和业务错误码为零。
5. 检查目标日志中的超时、认证、平台错误码和重试信息。

常见问题

现象	检查方法
HTTP 请求失败	URL、TLS 证书、防火墙、接收端状态码和目标日志。
平台配置无效	钉钉选择 DingTalk；企业微信选择 WeCom；普通接口选择 Custom。WeCom、Custom 不允许填写签名密钥，Custom 只允许 Raw。
接收端认证失败	钉钉检查完整 access_token URL、Secret 和系统时间；企业微信检查完整 key URL；自定义接口检查请求头 JSON、Token 格式和有效期。
请求成功但数据不对	消息格式、模板预览、实体字段和脚本输出。
钉钉返回 310000	根据 errmsg 检查关键词是否出现在消息内容、时间戳是否有效、Secret 是否匹配、出口公网 IP 是否在白名单。
钉钉返回 410100	发送速度太快；把多条报警合并为列表或 Markdown 摘要，并降低触发频率。
企业微信 Markdown 无效	平台必须选 WeCom；系统会生成 markdown.content。若使用 Raw，不要填写钉钉的 title、text 字段。
企业微信正文超限	Text 控制在 2048 UTF-8 字节内，Markdown 控制在 4096 UTF-8 字节内，并通过列表上传聚合或删减字段。
通知格式无效	检查平台与 Raw、Text、Markdown 组合；高级消息类型统一使用 Raw 并提供完整厂商 JSON。
请求超时	接口网络、接收端负载、请求超时和目标缓存状态。
测试请求失败	先执行“探测”确认 DNS 和 HEAD 可达，再检查 URL、请求头 JSON、签名密钥、消息格式和目标日志。
钉钉签名不正确	确认平台为 DingTalk，只填写机器人页面显示的 Secret，系统会自动追加 timestamp 和 sign，不要手工重复追加；检查 NTP 与时区。

官方协议参考

• 钉钉：自定义机器人发送群消息
• 钉钉：自定义机器人安全设置
• 钉钉：自定义机器人发送消息的消息类型
• 钉钉官方 GitHub 示例：GroupRobotUtil
• 企业微信：消息推送配置说明

相关操作

• 数据转发：配置转发组、触发、缓存和公共目标操作。
• 插件索引：查找其它采集或数据转发插件。