Webhook 通知

概述

Webhook 用于向外部系统的 HTTP 地址发送请求。管理员在「系统设置」中维护 Webhook 配置，包含请求地址、方法、认证、请求头、超时和重试参数，并可以向该地址发送一次测试请求验证连通性。

当前版本的实际能力：

也就是说，配置好的 Webhook 目前不会被平台事件自动调用，「测试」是唯一会发出请求的入口。需要事件通知的场景，请使用宿主事件在嵌入页面里接收报表事件，或由业务系统自己调用平台接口。

功能入口

系统 > 系统设置 > 「Webhook配置」 标签页，页面分三个面板：

操作步骤

新增并测试 Webhook

1. 在「Webhook配置」面板点击「新增Webhook配置」（或右上角 +），弹出「新增Webhook」对话框。
2. 填写「名称」和「请求地址」，在地址输入框前选择请求方法（GET、POST、PUT、DELETE、PATCH）。
3. 在「认证方式」选择对方接口要求的认证，并填写对应凭据。
4. 按需添加「请求头」，选择「Content-Type」，调整「超时时间」「重试次数」「重试间隔」。
5. 保持「启用」开启，点击保存，提示「创建成功」。
6. 在列表中该行的操作里点击「测试」，提示「正在发送测试请求...」，随后显示「测试成功！响应状态: 200」这样的结果，或「测试失败」及错误原因。

注意：测试必须先保存配置。对话框里在未保存时点击测试会提示「请先保存Webhook配置后再测试」。

查看发送记录

在「发送记录」面板可以按关键字（Webhook 名称或 URL）和「发送状态」筛选，点击某条记录打开「Webhook调用详情」，含 Webhook 名称、状态、请求方法、响应状态、URL、耗时、重试次数、发送时间，以及「请求体」「响应体」「错误信息」页签。

发送状态有四种：待发送、发送中、成功、失败。

设置自动清理

在「清理配置」面板设置后点击「保存」：

点击「立即清理」按上述保留规则立刻执行一次，确认后提示「已删除 N 条记录」。

属性/参数说明

认证方式

注意：「响应编码」「忽略SSL证书」「重试次数」「重试间隔」目前只随配置保存，测试请求不使用它们（测试请求只使用请求地址、方法、Content-Type、请求头、认证与超时时间）。

注意：需要签名的目标地址（如带加签的群机器人）不能直接使用「签名认证」。请改用对方支持的其他认证，或在地址里带上对方要求的静态参数。

测试请求

点击「测试」时，系统向配置的地址发送一次请求：

• 请求体默认为 {"test": true, "timestamp": <毫秒时间戳>}，在配置对话框内测试时额外带有 "source": "webhook_config_dialog"。
• GET 和 DELETE 请求不带请求体。
• 判定成功的标准是响应状态码在 200 到 299 之间。测试请求不会重试，也不会写入发送记录。
• 结果包含 success、statusCode、responseBody、duration（毫秒），异常时包含 error。

管理端接口

Webhook 接口只允许管理员的登录会话调用，请求头带 satoken，路径前缀 /api/admin/webhook。

BASE=https://your-domain
TOKEN=<管理员登录后的 satoken>

# 创建一个 Webhook
curl -s -X POST "$BASE/api/admin/webhook/configs" \
  -H "satoken: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"订单系统回调","url":"https://example.com/hook","method":"POST","authType":"BEARER","authConfig":{"token":"xxxx"},"contentType":"application/json","timeout":15000,"retryTimes":3,"retryInterval":5000,"enabled":true}'

# 用返回的 id 发送测试请求
curl -s -X POST "$BASE/api/admin/webhook/configs/test" \
  -H "satoken: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"webhookId":"<配置ID>","testPayload":{"hello":"sight"}}'

接口中的 timeout、retryInterval 单位为毫秒，与界面上的秒相差 1000 倍。authType 取值 NONE、BASIC、BEARER、API_KEY、SIGNATURE。

示例

用一个临时接收地址验证平台能否访问外部系统：

1. 在测试环境准备一个能返回 200 的 HTTP 地址，如内部的回调接收服务 https://hook.example.com/receive。
2. 新增 Webhook：名称「联通测试」，方法 POST，认证「无认证」，Content-Type 选 JSON，保存。
3. 点击列表里的「测试」。

预期：接收服务收到 {"test":true,"timestamp":...}，界面提示「测试成功！响应状态: 200」。如果显示「测试失败」，按提示的错误信息检查网络出口、域名解析和 HTTPS 证书。

注意事项

注意：Webhook 配置里保存的密码、Token、API Key 属于敏感凭据，配置界面仅限管理员访问。

提示：请求由平台服务器发出。目标地址必须能从服务器网络访问，与浏览器所在网络无关。

相关文档

• 宿主事件与方法调用
• 嵌入接口清单
• 登录集成
• 用户同步
• 三方集成应用