Webhooks 接入——通用事件入口 | Easy Understand Hermes Agent

这篇教程将带你了解 Hermes Agent 的 Webhooks 接入方式，让外部服务（如 GitHub、JIRA、Stripe 等）能自动触发智能体运行。

什么是 Webhooks？先打个比方

想象你家的门铃系统——Webhooks 就是智能体的“门铃”。当 GitHub 上有人提交了 Pull Request，就好比有人按了门铃，Hermes Agent 听到后就会自动“开门”处理：审查代码、回复评论、发消息通知你。

第 1 步：启动 Webhook 服务

有两种方式开启这个“门铃”：

方式一：使用设置向导

hermes gateway setup

按提示操作，启用 webhooks、设置端口和密钥即可。

方式二：直接改配置文件

在 ~/.hermes/.env 文件中添加：

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # 默认端口
WEBHOOK_SECRET=your-global-secret

启动后，验证服务是否正常运行：

curl http://localhost:8644/health

看到 {"status": "ok", "platform": "webhook"} 就说明门铃装好了！

第 2 步：配置“门铃规则”（Routes）

现在需要告诉 Hermes：按了门铃后该做什么。在 config.yaml 中定义路由规则：

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]          # 只响应 PR 事件
          secret: "github-webhook-secret"   # 门铃密码
          prompt: |
            请审查这个 Pull Request：
            仓库：{repository.full_name}
            PR 标题：{pull_request.title}
            作者：{pull_request.user.login}
          deliver: "github_comment"         # 回复到 GitHub 评论
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

关键概念解释：

events：监听哪些事件类型（如 pull_request、push）
secret：HMAC 签名密钥，用于验证消息确实来自可信来源
prompt：告诉智能体如何处理收到的数据，用 {点.语法} 提取关键信息
deliver：智能体的回复发到哪里（GitHub 评论、Telegram、Discord 等）

第 3 步：设置“门铃过滤器”（可选）

如果不想每次门铃响都处理，可以加过滤器。比如只处理标签包含 “hermes” 的任务：

filters:
  - field: "payload.labels"
    contains: "hermes"

第 4 步：把 Webhook 地址告诉外部服务

最后，去 GitHub/GitLab 等服务的设置页面，把 Webhook 地址填上：

http://your-server:8644/webhooks/github-pr

注意：地址中的 github-pr 就是你在配置中定义的路由名称。

进阶技巧

{__raw__} 魔法令牌：如果想看完整数据，在 prompt 中加上它，智能体就能收到全部原始信息
直接投递模式：设置 deliver_only: true 可跳过智能体，直接把消息转发出去，零成本、秒级响应

总结

Webhooks 接入就像给 Hermes Agent 装了个智能门铃——外部服务一有动静，它就能自动响应。核心三步：开启服务 → 配置路由规则 → 把地址告诉外部服务。配合过滤器，你还能精准控制哪些事件需要处理。

下篇预告：当外部服务无法主动推送时怎么办？下期我们将介绍 Polling 轮询接入——主动拉取事件，敬请期待！