Webhook 与外部事件注入——Huginn 的 HTTP 事件网关

Webhook 与外部事件注入——Huginn 的 HTTP 事件网关

学习目标

• 理解 Webhook URL 的三层路由设计
• 掌握 Agent 接收外部 HTTP 请求的方法约定
• 学会实现安全的签名令牌认证
• 了解统一响应格式的设计模式

前置知识

本章涉及外部事件注入的通用原理，建议先阅读：

• 外部事件注入与 Webhook 集成

下文假设你已理解 Webhook 的基本概念，直接聚焦 Huginn 的具体实现。

项目实践

三层路由设计

/users/:user_id/web_requests/:agent_id/:secret
 ↑              ↑              ↑       ↑
 用户范围定位   Agent 定位      签名令牌

关键安全设计：

• 跳过 CSRF 验证（skip_before_action :verify_authenticity_token）
• 跳过用户认证（skip_before_action :authenticate_user!）
• 但保留用户和 Agent 的归属验证——请求只能路由到正确的 user_id 和 agent_id
• 最终的签名令牌验证由 Agent 内部完成

Agent 方法约定

Agent 实现 receive_web_request 方法，返回统一格式的数组：

def receive_web_request(params, method, format)
  # params: 请求参数
  # method: "get" / "post" / 其他 HTTP 方法
  # format: "json" / "xml" / "html"

  # 返回格式: [body, status, content_type?, headers?]
  ["success", 200]                                        # 纯文本
  [{ status: "ok", data: result }, 200]                   # JSON
  ["<status>success</status>", 200, "text/xml"]           # 自定义 MIME
  ["redirect_url", 302]                                   # 重定向
  [{}, 200, "text/plain", {"Access-Control-Allow-Origin" => "*"}]  # 自定义头

控制器自动处理返回值：

web_requests_controller.rb

if status.to_s.in?(%w[301 302])
  redirect_to(content, status:)
elsif content.is_a?(String)
  render plain: content, status:, content_type: content_type || 'text/plain'
elsif content.is_a?(Hash)
  render json: content, status:
else
  head(status)
end

实际应用场景

GitHub Webhook Agent 示例：

def receive_web_request(params, method, format)
  return ["invalid secret", 403] unless params[:secret] == options[:secret]

  case params[:headers]['X-GitHub-Event']
  when 'push'
    create_event(payload: params)
    ["ok", 200]
  when 'issues'
    create_event(payload: params)
    ["ok", 200]
  else
    ["ignored event", 200]
  end
end

问题与规避

签名令牌泄露

Webhook URL 中的 secret 暴露在 URL 中，可能被日志或代理记录。

规避方式：

• 使用 HTTPS 加密传输
• 定期轮换 secret（更新 Agent 配置）
• 对于高安全场景，在 Agent 内部验证外部系统的签名（如 Stripe 签名头）

GET 请求的 CSRF 风险

跳过 CSRF 验证后，恶意页面可能通过 <img> 或 <iframe> 发送 GET 请求。

规避方式：

• GET 请求不产生副作用（仅读取数据或返回状态）
• 有副作用的操作使用 POST
• Secret 令牌阻止了未授权的 POST 操作

设计取舍

URL 路由 vs Header 认证

维度	URL 路由（secret 在 URL 中）	Header 认证（Bearer token）
配置简单度	高（一个 URL）	中（需要配置 header）
安全性	中（URL 可能被日志记录）	高（header 不进入日志）
兼容性	高（所有外部系统都支持）	中（部分系统不支持自定义 header）

Huginn 选择 URL 路由是因为兼容性优先——任何能发送 HTTP 请求的系统都能使用 Webhook，不需要支持自定义 Header。

参考来源

• Webhooks.org — Webhook 技术标准
• GitHub Webhooks 文档 — 外部系统 Webhook 实现参考