Webhook Gateway 镜像文档

镜像概述

Webhook Gateway 是一个轻量级、高性能的webhook请求处理中间件，旨在简化跨服务间的webhook集成流程。该镜像提供统一的webhook接入点，支持请求验证、数据转换、规则路由等核心能力，解决多服务webhook管理中的安全验证复杂、格式不统一、转发规则分散等问题，降低跨服务事件通知的集成成本。

核心功能与特性

• 请求验证：支持多种验证机制，包括HMAC签名验证（如GitHub、GitLab风格）、Token验证等，防止未授权请求
• 请求转换：提供内置数据转换能力，支持JSON/XML格式转换、字段映射、数据过滤，统一输出格式
• 智能路由：基于请求头、路径、 payload 字段等规则，将webhook请求转发至不同后端服务
• 日志与监控：内置请求日志记录，支持输出至标准输出或文件，便于问题排查与监控
• 错误处理：支持自定义错误响应、重试机制及失败回调，提升webhook处理可靠性
• 轻量级设计：基于高效运行时（如Go、Node.js）构建，资源占用低，启动速度快

使用场景与适用范围

典型使用场景

• 多服务webhook集成：统一管理来自GitHub、GitLab、Jenkins、Slack等多平台的webhook请求
• 第三方服务事件处理：处理支付平台回调、消息通知等第三方服务事件，转换为内部系统可识别格式
• webhook安全加固：集中处理webhook签名验证，避免各业务服务重复实现验证逻辑
• 请求流量控制：对webhook请求进行限流、过滤，保护后端服务免受突发流量冲击

适用人群

• 需要集成多个第三方服务webhook的开发者
• 负责服务间事件通知架构的运维人员
• 需对webhook请求进行安全验证与格式统一的技术团队

使用方法与配置说明

基本使用（Docker Run）

bash
docker run -d \
  --name webhook-gateway \
  -p 8080:8080 \
  -e PORT=8080 \
  -e VALIDATION_SECRET=your_webhook_secret \
  -e TARGET_URL=[***] \
  webhook-gateway:latest

Docker Compose 配置示例

yaml
version: '3'
services:
  webhook-gateway:
    image: webhook-gateway:latest
    container_name: webhook-gateway
    ports:
      - "8080:8080"
    environment:
      - PORT=8080  # 监听端口，默认8080
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error，默认info
      - VALIDATION_TYPE=hmac  # 验证类型：hmac/token/none，默认none
      - VALIDATION_SECRET=your_hmac_secret  # 验证密钥，当VALIDATION_TYPE为hmac/token时必填
      - TARGET_BASE_URL=[***]  # 默认转发基础URL
    volumes:
      - ./routes.yaml:/app/routes.yaml  # 路由规则配置文件（可选）
    restart: unless-stopped

环境变量说明

路由规则配置

通过挂载路由配置文件（如routes.yaml）实现复杂路由逻辑，配置示例：

yaml
routes:
  - name: github-webhook  # 路由名称
    match:  # 匹配规则
      path: /github  # 匹配请求路径
      headers:
        X-GitHub-Event: push  # 匹配请求头
    validate:  # 路由级验证配置（覆盖全局配置）
      type: hmac
      secret: github_webhook_secret
      header: X-Hub-Signature-256
    transform:  # 数据转换规则
      type: json
      mapping:  # 字段映射，将源字段映射到目标字段
        event_type: $.action
        repo: $.repository.name
        sender: $.sender.login
    target: [***]  # 转发目标URL
  - name: slack-notification
    match:
      path: /slack
    validate:
      type: token
      secret: slack_bot_token
      header: Authorization
    target: [***]

启动与验证

1. 启动容器后，通过curl发送测试请求验证：

   bash
   curl -X POST http://localhost:8080/github \
     -H "Content-Type: application/json" \
     -H "X-GitHub-Event: push" \
     -d '{"action":"published","repository":{"name":"my-app"},"sender":{"login":"user123"}}'
   

2. 查看容器日志确认请求处理状态：

   bash
   docker logs -f webhook-gateway
   

注意事项

• 生产环境中建议使用路由配置文件（routes.yaml）管理复杂规则，避免环境变量过多导致配置混乱
• 敏感信息（如验证密钥）建议通过Docker Secrets或环境变量注入，避免硬编码
• 高并发场景下可水平扩展多个实例，配合负载均衡器使用
• 定期清理日志文件，避免磁盘空间占用过大