☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望 Hermes Agent 接收来自外部系统（如飞书、企业微信、GitHub、Webhook 等）的实时事件通知，则需正确配置 Webhook 服务端点及签名验证机制。以下是完成该配置的具体操作路径：
一、确认 Hermes Webhook 服务已启用并监听指定路径
Hermes Agent 默认提供统一 Webhook 入口，需确保服务进程正在运行且能响应外部 HTTP POST 请求。Webhook 路径由网关类型决定，例如 /webhook/feishu、/webhook/wecom 或通用路径 /webhook/generic（需手动启用）。该步骤旨在暴露可被公网访问的回调地址，并避免因服务未启动或端口阻塞导致请求超时或拒绝。
1、检查 Hermes 进程是否运行：执行 hermes status 命令确认状态为 active。
2、确认配置文件中对应网关的 enabled: true 已设置，且 webhook 相关字段无语法错误。
3、验证本地端口监听：执行 netstat -tuln | grep :3000（默认端口为 3000），确认有 LISTEN 状态条目。
4、若部署于云服务器，检查安全组或防火墙是否放行目标端口（如 TCP 3000）及对应域名的 HTTPS 443 端口（如使用反向代理）。
二、配置反向代理与 TLS 证书（适用于公网回调）
多数外部平台（如飞书、企业微信）强制要求 Webhook URL 使用 HTTPS 协议，且需通过可信 CA 签发的证书。直接暴露 Hermes 内置 HTTP 服务不可行，必须通过 Nginx 或 Caddy 等反向代理进行协议升级与路径转发。该步骤确保回调请求能被安全、稳定地送达 Hermes 实例。
1、安装并启动 Nginx：在 Ubuntu 系统中执行 sudo apt install nginx && sudo systemctl enable --now nginx。
2、获取 SSL 证书：使用 Certbot 自动申请 Let's Encrypt 证书，命令为 sudo certbot --nginx -d your-domain.com。
3、编辑 Nginx 配置文件（如 /etc/nginx/sites-available/your-domain），添加 location 块：location /webhook/ { proxy_pass http://127.0.0.1:3000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }。
4、重载配置：sudo nginx -t && sudo systemctl reload nginx。
三、设置外部平台的 Webhook 回调地址与验证参数
各平台在注册 Webhook 时均要求提供 URL、Token 和 EncodingAESKey（或类似签名密钥），这些值必须与 Hermes 配置文件中的对应字段完全一致，否则签名校验失败，请求将被丢弃。该步骤建立双向身份信任链，防止伪造事件注入。
1、登录飞书开放平台，在“事件订阅”页面填写 URL：https://your-domain.com/webhook/feishu，Token 和 Encrypt Key 必须与 config.yaml 中 verification_token 和 encrypt_key 完全匹配。
2、登录企业微信管理后台，在“应用管理 → 自建应用 → 接收消息”中设置 URL：https://your-domain.com/webhook/wecom，Token 与 AESKey 必须分别等于配置项中的 token 和 aes_key。
3、对于通用 Webhook（如 GitHub），启用 gateways.generic.enabled: true，并在 Hermes 配置中定义 generic_secret: "your-secret"；外部系统需在请求头中携带 X-Hub-Signature-256，其值为 HMAC-SHA256(secret, payload) 的十六进制表示。
四、验证 Webhook 签名与事件解析逻辑
Hermes 对接收到的每个 Webhook 请求执行严格签名比对与 JSON 结构解析。若 Token 或密钥不一致、时间戳偏差超 300 秒、或 body 体被篡改，请求将被静默拒绝。该步骤用于定位常见 401/403 错误根源，确保事件内容可被正确路由至 AI 处理流水线。
1、查看 Hermes 日志实时输出：hermes logs -f，观察是否出现 "Invalid signature" 或 "Missing token header" 提示。
2、使用 curl 模拟合法飞书回调请求：curl -X POST https://your-domain.com/webhook/feishu -H "Content-Type: application/json" -H "X-Feishu-Timestamp: $(date +%s)" -H "X-Feishu-Signature: $(echo -n "$(date +%s)your_verification_token" | openssl dgst -sha256 -hmac "your_app_secret" | awk '{print $2}')" -d '{"type":"url_verification","challenge":"xxx"}'。
3、检查 Hermes 控制台是否返回 {"challenge":"xxx"}，表明签名与路由逻辑正常。
五、启用并测试通用 Webhook 网关（支持自定义事件源）
当接入非标准平台（如内部 CI 系统、IoT 设备或低代码平台）时，可启用 generic 网关接收任意结构的 POST 请求。Hermes 将原始 payload 作为上下文传入 LLM，由提示词工程决定如何响应。该步骤扩展 Hermes 的集成边界，无需为每类系统单独开发适配器。
1、编辑 ~/.hermes/config.yaml，添加或修改以下内容：gateways: generic: enabled: true secret: "my-custom-webhook-secret"。
2、重启 Hermes：hermes restart。
3、构造测试请求，Header 中包含 X-Generic-Secret: my-custom-webhook-secret，Body 为任意 JSON 对象，例如 {"event": "deploy_success", "service": "backend-api", "version": "v2.4.1"}。
4、在 Hermes 日志中确认是否打印出完整 payload，并检查会话中是否生成对应响应。
