Hermes Webhook 事件触发：让外部世界自动叫醒 AI

Cron 是到点上班，Webhook 是有人敲门。 GitHub 提了 Issue？Stripe 收到付款？监控报警了？Webhook 让 Hermes 自动响应这些外部事件。

一、Webhook 是什么？跟 Cron 有什么区别？

Cron 和 Webhook 是 Hermes 自动化的两条腿：

什么时候用哪个？

我想让 AI 做的事情…
├─ 每天固定时间做 → Cron
├─ 每 30 分钟检查一次 → Cron
├─ 有事情发生时马上做 → Webhook ⬅
└─ 外部系统通知我时做 → Webhook ⬅

Webhook 的核心就是：你在 GitHub/Stripe/监控系统里配一个 URL，当有事发生时，它们 POST 一个 JSON 到 Hermes，Hermes 收到后自动处理并把结果投递给你。

二、快速上手：第一个 Webhook

2.1 前提条件

Webhook 服务器是 Hermes Gateway 的一部分。需要先确认 Gateway 在运行：

hermes gateway status

如果没跑，启动它：

hermes gateway run # 前台测试
hermes gateway install # 后台服务
hermes gateway start

2.2 启用 Webhook 平台

Webhook 平台默认不开启，需要手动启用：

hermes gateway setup

在交互式向导里选择启用 Webhooks，设定端口（默认 8644）和 HMAC 密钥。

或者手动配 ~/.hermes/config.yaml：

platforms:
webhook:
enabled: true
extra:
host: "0.0.0.0"
port: 8644
secret: "你生成的一个强密钥"

2.3 创建第一个订阅

hermes webhook subscribe demo-alert \\
–prompt "收到一条告警：{message}，请分析严重程度并给出处理建议" \\
–deliver telegram

创建成功后，CLI 会返回两个东西：

Webhook URL: http://你的服务器地址:8644/webhooks/demo-alert
HMAC Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

把 URL 和 Secret 配置到你的外部系统里。当外部系统 POST 一个 JSON 到那个 URL 时，Hermes 就会自动处理。

2.4 测试

不等外部系统触发，手动模拟：

hermes webhook test demo-alert

或者带上自定义 payload：

hermes webhook test demo-alert \\
–payload '{"message": "数据库连接池耗尽，连接数超过阈值 90%"}'

Hermes 会收到这个 JSON，用模板里的 {message} 展开，自动分析并推送结果到你的 Telegram。

三、订阅管理

查看所有订阅

hermes webhook list

输出：

┌──────────────┬──────────────────────────────────────┬──────────┬──────────┐
│ Name │ URL │ Events │ Deliver │
├──────────────┼──────────────────────────────────────┼──────────┼──────────┤
│ demo-alert │ /webhooks/demo-alert │ * │ telegram │
│ github-issue │ /webhooks/github-issue │ issues │ telegram │
└──────────────┴──────────────────────────────────────┴──────────┴──────────┘

删除订阅

hermes webhook remove demo-alert

测试订阅

hermes webhook test github-issue –payload '{"issue": {"title": "登录页面报500", "number": 42}}'

四、Prompt 模板——如何引用外部数据

Webhook 最巧妙的设计是 Prompt 模板。外部系统 POST 过来的 JSON 里的字段，可以用 {dot.notation} 语法嵌入到任务描述中。

基本用法

如果外部 POST 的 JSON 是：

{
"issue": {
"title": "登录页面报 500 错误",
"number": 42,
"user": { "login": "zhangsan" }
}
}

模板写成：

新 Issue #{issue.number}：{issue.title}
作者：{issue.user.login}
请分析这个 Issue 的严重程度并给出排查建议

Hermes 收到后会自动把模板展开成：

新 Issue #42：登录页面报 500 错误
作者：zhangsan
请分析这个 Issue 的严重程度并给出排查建议

事件过滤

如果你只想在某些特定事件发生时触发：

hermes webhook subscribe github-issues \\
–events "issues,issue_comment" \\
–prompt "…"

只有 POST 请求的 headers 或 body 里包含 "event": "issues" 或 "event": "issue_comment" 才会触发。不指定 –events 就接收所有。

直接投递模式（零 token 成本）

有些场景不需要 AI 理解上下文，只需要把外部消息原样转发到你的聊天窗口。

hermes webhook subscribe antenna-matches \\
–deliver telegram \\
–deliver-chat-id "123456789" \\
–deliver-only \\
–prompt "🎉 新匹配：{match.user_name} 和你配对成功！"

–deliver-only 模式：零 LLM 调用、零 token 消耗。模板渲染后直接投递。适合：

• 外部服务的推送通知（Supabase/Firebase → Telegram）
• 监控告警原样转发
• 智能体之间的跨系统通知

五、实战场景

场景 1：GitHub Issue 自动分类

把 Hermes 和 GitHub 仓库连起来——有人提 Issue 就自动分析、打标签、分配负责人。

配置订阅：

hermes webhook subscribe github-issues \\
–events "issues" \\
–prompt "
新 Issue #{issue.number}：{issue.title}
作者：{issue.user.login}
内容：{issue.body}

请完成以下工作：
1. 分析这个 Issue 的类型（bug / feature / 文档 / 问题）
2. 评估优先级（P0紧急 / P1高 / P2中 / P3低）
3. 给出初步排查建议
4. 如果是 bug，列出可能需要检查的模块方向
" \\
–deliver telegram

GitHub 配置：

进 GitHub 仓库 → Settings → Webhooks → Add webhook：

• Payload URL： 从 hermes webhook subscribe 返回的 URL
• Content type： application/json
• Secret： 返回的 HMAC Secret
• Events： 选 "Issues"

效果： 有人提 Issue → GitHub POST 到 Hermes → AI 分析类型和优先级 → 结果推到你手机 → 你看一眼就知道该不该马上处理。

场景 2：GitHub PR 自动 Review

PR 提交时自动触发代码审查，结果直接评论回 PR 里。

hermes webhook subscribe github-prs \\
–events "pull_request" \\
–prompt "
PR #{pull_request.number}：{pull_request.title}
作者：{pull_request.user.login}
分支：{pull_request.head.ref} → {pull_request.base.ref}
描述：{pull_request.body}

请 review 这个 PR 的代码变更，重点关注：
1. 潜在的 bug 和逻辑错误
2. 安全问题
3. 测试覆盖是否充分
4. 代码风格是否一致

把 review 结果直接评论回 PR。
" \\
–deliver github_comment \\
–skills "github-code-review"

–deliver github_comment 会把 AI 的 review 结果直接作为 GitHub 评论发回 PR 里。

场景 3：Stripe 付款事件通知

客户付款成功或失败时，AI 自动分析并通知你。

hermes webhook subscribe stripe-payments \\
–events "payment_intent.succeeded,payment_intent.payment_failed" \\
–prompt "
付款事件：{type}
金额：{data.object.amount} 美分
客户邮箱：{data.object.receipt_email}
状态：{data.object.status}

{type} 包含 'succeeded':
请确认订单状态已更新，并通知客户发货
{type} 包含 'failed':
请分析可能的原因（余额不足 / 卡无效 / 风控拦截），给出后续建议
" \\
–deliver telegram

场景 4：CI/CD 构建通知

GitLab CI 或 GitHub Actions 构建完成后，AI 分析结果并总结。

hermes webhook subscribe ci-builds \\
–prompt "
构建状态：{object_attributes.status}
项目：{project.name}
分支：{object_attributes.ref}
提交信息：{commit.message}

分析这个构建结果，如果失败列出可能的原因和修复建议。
" \\
–deliver discord

场景 5：监控报警——使用直接投递模式

这是最省 token 的模式——监控系统发来的报警直接转发，不走 LLM。

hermes webhook subscribe server-alerts \\
–prompt "
🚨 **{alert.severity}** – {alert.name}

服务器：{alert.host}
指标：{alert.metric}
当前值：{alert.value}
阈值：{alert.threshold}

时间：{alert.timestamp}
" \\
–deliver telegram \\
–deliver-only

零 token 消耗，监控报警直接推到你手机。只有需要 AI 分析时才开 agent 模式。

场景 6：智能家居事件

家里的 IoT 传感器（温度、湿度、门窗传感器）触发事件时，AI 分析并给出建议。

hermes webhook subscribe home-sensor \\
–events "temperature,humidity,motion" \\
–prompt "
传感器事件：{sensor.type}
位置：{sensor.location}
当前值：{sensor.value}
单位：{sensor.unit}

分析这个读数是否正常。
如果不正常，给出建议（例如：开空调、关窗户、检查异常活动）。
" \\
–deliver telegram

六、安全机制

HMAC 签名验证

每个 Webhook 订阅都会自动生成一个 HMAC-SHA256 secret。外部系统 POST 请求时，需要在 header 里带上签名。Hermes 验证签名后才处理。

GitHub 用 X-Hub-Signature-256 header，GitLab 用 X-Gitlab-Token。

这样即使别人知道了你的 Webhook URL，没有 secret 也发不了有效的请求。

自定义 Secret

不想用自动生成的，也可以自己指定：

hermes webhook subscribe my-service \\
–secret "your-custom-secret" \\
–prompt "…"

静态路由保护

~/.hermes/config.yaml 里配的静态路由，不会被动态订阅覆盖。防止有人通过 API 篡改你的核心配置。

七、需要公网地址怎么办？

这是 Webhook 跟 Cron 最大的不同——Cron 不需要公网，Webhook 需要外部系统能访问到你的 Hermes。

如果你在本地或内网跑 Hermes，有以下选择：

方案 1：内网穿透（推荐新手）

用 ngrok 或 cloudflared 暴露本地端口：

# ngrok
ngrok http 8644
# 得到 https://xxxx.ngrok-free.app

# 或 cloudflared（Cloudflare Tunnel）
cloudflared tunnel –url http://localhost:8644
# 得到 https://xxxx.trycloudflare.com

穿透后的 URL 就是你的 Webhook 地址。加上路径 /webhooks/订阅名称 就是完整 URL。

方案 2：公网服务器

如果你已经有公网服务器，直接把 Gateway 部署在上面，端口 8644 暴露出去。

方案 3：反向代理（Nginx）

server {
listen 443 ssl;
server_name webhook.yourdomain.com;

location /webhooks/ {
proxy_pass http://localhost:8644;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}

八、故障排查

Webhook 没触发？

GitHub 连不上？

• 确保 Payload URL 是公网可访问的（不是 localhost）
• 确认 Content type 选了 application/json
• GitHub 会发送测试 ping，检查是否收到

收到了但没处理？

• 确认 –events 过滤没写错
• 用 hermes webhook test 名称 手动模拟一次

九、Webhook + Cron 组合拳

两个一起用才是完全体：

Cron（每天 8 点）：检查所有正在进行的 Issue 状态，做一次汇总
Webhook（随时触发）：新 Issue 进来时自动分类

Cron（每 5 分钟）：检查服务器负载
Webhook（随时触发）：监控系统发现异常时直接报警

Cron（每天早上）：整理昨天的 Stripe 交易记录
Webhook（随时触发）：大额付款实时通知你

Cron 负责"定时查"，Webhook 负责"随时推"。 两者结合，你的 AI 助理就从一个被动应答工具，变成了一个主动工作的智能体系统。

十、总结

核心思想： Cron 让你按时找 AI，Webhook 让世界帮你叫 AI。两个都配好，你的 Hermes 才算是真正在干活——不是等你叫它，而是该干活的时候它自己就知道。