Agent对接WebHook，任务完成回调通知外部业务系统
200.Agent 本身负责调度和执行任务，但很多业务场景要求任务结束后及时通知外部系统，比如更新工单状态、触发后续流程或同步执行结果。
通过配置 WebHook，Agent 可以在任务完成时主动向外部业务系统发送 POST 请求，比轮询接口更实时也更省资源。
本文按零基础可照做的顺序，介绍准备条件、配置步骤、接收端写法、避坑要点和验证方法。
一、对接前需要准备什么
开始前请确认以下内容已经具备：
- 一台可运行或已运行 200.Agent 服务的服务器，且能访问公网。
- 外部业务系统提供一个可接收 WebHook 的 HTTP 接口。如果是本地测试，可以使用内网穿透工具暂时暴露端口。
- 明确回调数据里需要包含哪些字段，比如任务ID、任务状态、开始时间、结束时间、执行结果等。
- 准备一个密钥（secret），用于请求签名校验，避免伪造回调。
二、在 Agent 端配置 WebHook 地址
200.Agent 一般支持通过配置文件或管理控制台设置 WebHook。
这里以配置文件方式举例，找到 Agent 的配置文件 agent.yaml，添加如下内容：
webhook:
url: https://your-business-system.com/hook/agent
secret: your-secret-key
events:
- task.finished
- task.failed如果使用控制台，通常在「系统设置 → 通知设置 → WebHook」中填写回调地址和密钥，并勾选任务完成事件。
保存后建议先点击测试按钮，确认接收端能收到测试请求。
三、外部系统如何接收回调
回调通常是 POST 请求，Content-Type 为 application/json，请求体类似：
{
"task_id": "1725443210",
"status": "success",
"timestamp": 1735000000,
"result": {"code": 0}
}接收端需要校验签名，确认请求来自 Agent。
下面是一个 Flask 示例（其他语言同理）：
import hmac
import hashlib
from flask import Flask, request
app = Flask(__name__)
SECRET = "your-secret-key"
@app.route("/hook/agent", methods=["POST"])
def webhook():
body = request.get_data()
sign = request.headers.get("X-Signature", "")
expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sign, expected):
return "invalid signature", 403
data = request.get_json()
print(f"task {data['task_id']} -> {data['status']}")
return "ok", 200
if __name__ == "__main__":
app.run(port=5000)如果你的 Agent 使用不同的签名方式，建议以官方文档为准。
签名校验是防止第三方伪造回调的关键一步，不要省略。
四、避坑指南与高频疑问
回调地址必须公网可达，且接收方要返回 200。 如果 Agent 重试多次后放弃，任务状态可能丢失。
外部系统处理完业务后务必返回 200 OK，否则 Agent 会继续重试。
回调可能重复推送。 网络抖动或接收方超时会触发 Agent 重试，业务系统要做幂等处理，比如用 task_id 加状态做去重。
签名校验失败怎么办？ 检查密钥是否一致，确认签名计算用的原始数据是不是完整的请求体。
不要在签名前对 JSON 做格式化或重新编码。
接收方无法访问内网 Agent？ 这里指的是 Agent 主动访问外部系统，外部系统不需要访问 Agent，所以只要 Agent 能访问公网即可。
支持自定义回调字段吗？ 部分版本支持在 WebHook 配置中增加固定参数或自定义模板。
如果暂时不支持，可以在接收端根据 task_id 再查询任务详情。
五、验证任务完成回调是否生效
- 在 200.Agent 中执行一个测试任务，例如让任务运行后立即返回成功。
- 观察外部业务系统日志，确认收到
POST /hook/agent请求。 - 检查响应状态码是否未
200，以及数据字段是否完整。 - 使用错误的
X-Signature手动请求一次，确认被拒绝，证明签名验证有效。
如果整个流程都通过，说明 200.Agent 对接 WebHook 已经配置成功。
今后每个任务完成时，外部业务系统都会第一时间收到通知，无需再额外轮询。
如果你的 Agent 版本较旧，个别配置项可能叫“回调地址”或“Notification URL”，本质一致。
遇到异常时优先查看 Agent 日志和接收端日志，大多能直接定位问题。
