rycus86/webhook-proxy

Webhook Proxy

概述

Webhook Proxy是一个基于Python Flask框架的轻量级REST服务器，用于接收JSON格式的webhook请求，并根据配置执行一系列预设动作。支持多架构Docker镜像（x86、32位ARM、64位ARM），可灵活配置请求验证规则和动作逻辑。

核心功能

• 接收并验证JSON webhook请求（支持请求头、请求体的正则验证）
• 执行多种动作：日志记录、外部命令执行、HTTP请求发送、Docker/Docker Compose操作
• 支持Jinja2模板变量，实现动态参数注入
• 多架构Docker镜像支持，适配不同硬件环境

使用场景

• GitHub/GitLab推送事件触发自动化处理（如代码构建、通知）
• Docker镜像更新后自动重启相关容器
• 外部系统事件触发内部服务操作（如数据同步、告警）

配置说明

配置文件采用YAML格式，包含server、endpoints、actions三个核心部分：

1. Server配置

定义HTTP服务器监听参数：

设置host: 0.0.0.0可允许外部访问。

2. Endpoints配置

定义webhook端点，支持以下参数：

• method: HTTP方法（默认POST）
• headers: 请求头验证规则（键为头名称，值为正则表达式）
• body: 请求体JSON验证规则（嵌套结构支持列表）
• actions: 合法请求触发的动作列表

3. Actions配置

支持多种动作类型：

• log: 打印日志（支持Jinja2模板）
• execute: 执行外部命令
• http: 发送HTTP请求（需requests模块）
• docker: 操作Docker容器（需docker模块和/var/run/docker.sock挂载）
• docker-compose: 操作Docker Compose项目（需docker-compose模块）

Docker部署示例

普通版（无Docker操作权限）

shell
docker run -d --name=webhook-proxy -p 5000:5000 \
  -v $PWD/server.yml:/app/server.yml \
  rycus86/webhook-proxy:latest

支持Docker操作版

shell
docker run -d --name=webhook-proxy -p 5000:5000 \
  -v $PWD/server.yml:/app/server.yml \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  rycus86/webhook-proxy:docker

Docker Compose示例（64位ARM）

yaml
version: '2'
services:
  webhooks:
    image: rycus86/webhook-proxy:aarch64
    ports:
      - 8080:5000
    volumes:
      - ./webhook-server.yml:/app/server.yml:ro

示例配置

以下是GitHub推送事件处理的配置示例：

yaml
server:
  host: '0.0.0.0'
  port: '7000'
endpoints:
  - /github:
      method: 'POST'
      headers:
        X-GitHub-Delivery: '^[0-9a-f\-]+

更多配置示例可参考项目https://github.com/rycus86/webhook-proxy。
        X-GitHub-Event: 'push'
      body:
        ref: 'refs/heads/.+'
        repository:
          full_name: 'sample/.+'
      actions:
        - log:
            message: |
              收到GitHub推送：{{ request.json.repository.full_name }}
              推送者：{{ request.json.pusher.name }}

更多配置示例可参考项目https://github.com/rycus86/webhook-proxy%E3%80%82