ncarlier/webhookd

webhookd

一个非常简单的webhook服务器，用于启动shell脚本。

!https://github.com/ncarlier/webhookd/raw/master/webhookd.svg

概述

webhookd是一个轻量级的webhook服务器，允许通过HTTP请求触发shell脚本执行。它设计简洁，配置灵活，支持多种参数传递方式、实时日志流、通知机制、认证与签名验证等功能，适用于自动化部署、CI/CD流程触发、简单任务调度等场景。

核心功能与特性

• 简单易用：通过目录结构定义webhook，脚本即服务
• 灵活配置：支持命令行参数或环境变量配置
• 多参数传递：URL参数、HTTP头、请求体均可转换为脚本变量
• 实时日志：支持Server-sent events (SSE) 和Chunked Transfer Coding实时流日志
• 超时控制：全局和请求级别的超时配置
• 通知机制：支持HTTP和Email通知，可过滤脚本输出
• 安全保障：HTTP基本认证、请求签名验证（HTTP Signatures和Ed25519）、TLS加密
• 多安装方式：支持Go安装、二进制下载、Docker部署、APT包管理

安装与部署

Docker部署

基本部署

bash
$ docker run -d --name=webhookd \
  -v ${PWD}/scripts:/scripts \
  -p 8080:8080 \
  ncarlier/webhookd

高级功能镜像

官方镜像轻量适用于简单脚本，如需高级功能（如Docker CLI或Docker Compose交互），可使用ncarlier/webhookd:edge-distrib镜像：

bash
$ docker run -d --name=webhookd \
  -v ${PWD}/scripts:/scripts \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:8080 \
  ncarlier/webhookd:edge-distrib

配置说明

webhookd可通过命令行参数或环境变量配置，执行webhookd -h查看所有参数及对应环境变量。所有配置变量详见https://github.com/ncarlier/webhookd/blob/master/etc/default/webhookd.env%E6%96%87%E4%BB%B6%E3%80%82

核心配置项：

• WHD_SCRIPTS/-script：脚本目录路径（默认./scripts）
• WHD_HOOK_TIMEOUT：全局webhook超时时间（秒，默认10）
• WHD_HOOK_LOG_DIR：日志存储目录
• WHD_NOTIFICATION_URI：通知目标URI（HTTP或Email）
• WHD_PASSWD_FILE：htpasswd认证文件路径
• WHD_TRUST_STORE_FILE：签名验证公钥文件（PEM格式）
• WHD_TLS：启用TLS（true/false）
• WHD_TLS_DOMAIN：ACME域名（启用ACME时）

使用方法

目录结构

webhook通过脚本目录结构定义，默认位于./scripts（可通过WHD_SCRIPTS修改）。目录结构示例：

/scripts
├── /github
│   ├── build.sh
│   └── deploy.sh
├── push.js
└── echo.sh

注：支持任何可执行文件（需添加shebang头），如.sh、.js等。

Webhook URL

URL路径对应脚本路径，可省略脚本扩展名（默认查找.sh文件）。示例：

• 脚本/scripts/github/build.sh对应URL：http://localhost:8080/github/build
• 脚本/scripts/echo.sh对应URL：http://localhost:8080/echo

响应流类型

• SSE（Server-sent events）：使用GET方法且Accept: text/event-stream头
• Chunked Transfer：其他情况（如POST方法或默认GET）

参数传递

脚本参数来源及转换规则：

1. URL请求参数：转换为脚本变量（如?foo=bar → foo=bar）
2. HTTP头：转换为snakecase变量（如Content-Type → content_type）
3. 请求体：
   • application/x-www-form-urlencoded：键值对转换为变量
   • text/*或application/json：作为脚本第一个参数传递

额外内置变量：

• hook_id：自动递增的hook ID
• hook_name：hook名称
• hook_method：HTTP请求方法
• x_forwarded_for：客户端IP
• x_webauth_user：认证用户名（若启用认证）

超时配置

• 全局超时：通过WHD_HOOK_TIMEOUT环境变量设置（秒）
• 请求级超时：通过X-Hook-Timeout HTTP头覆盖（秒）

示例：

bash
curl -H "X-Hook-Timeout: 5" http://localhost:8080/echo?foo=bar

日志管理

• 实时日志：webhook调用时实时流式输出
• 历史日志：通过X-Hook-ID头获取的ID访问http://localhost:8080/<NAME>/<ID>查看历史日志

通知机制

脚本执行后可发送通知，仅输出中以特定前缀（默认notify:）开头的行将被发送。通过WHD_NOTIFICATION_URI配置通知目标。

HTTP通知

配置URI：http://example.org?prefix=notify:（prefix可选，默认notify:）

POST payload格式：

json
{
  "id": "42",
  "name": "echo",
  "text": "notify: Hello World\n",
  "error": "错误信息（如有）"
}

支持Mattermost、Slack、***等webhook端点。

Email通知

配置URI：mailto:user@example.com?smtp=smtp.example.com:587&username=user&password=pass&from=webhookd@example.com

支持参数：smtp（SMTP服务器）、username/password（认证信息）、conn（连接类型：tls/tls-insecure/plain）、from（发件人）、subject（主题）。

认证配置

通过htpasswd文件启用HTTP基本认证：

1. 创建htpasswd文件：

bash
htpasswd -B -c .htpasswd api

2. 配置认证文件路径：

bash
export WHD_PASSWD_FILE=/path/to/.htpasswd

3. 使用认证访问：

bash
curl -u api:password -XPOST "http://localhost:8080/echo?msg=hello"

签名验证

支持HTTP Signatures和Ed25519签名验证，需配置公钥文件（PEM格式）：

bash
export WHD_TRUST_STORE_FILE=/path/to/pubkey.pem

HTTP Signatures示例：

bash
curl -X POST \
  -H 'Date: Wed, 21 Oct 2015 07:28:00 GMT' \
  -H 'Signature: keyId="my-key",algorithm="rsa-sha256",headers="(request-target) date",signature="base64-signature"' \
  "http://localhost:8080/echo?msg=hello"

Ed25519签名示例：

bash
curl -X POST \
  -H 'X-Signature-Timestamp: 1620000000' \
  -H 'X-Signature-Ed25519: base64-signature' \
  "http://localhost:8080/echo?msg=hello"

TLS配置

启用TLS加密：

1. 自定义证书：

bash
docker run -d --name=webhookd \
  -v ${PWD}/scripts:/scripts \
  -v ${PWD}/certs:/certs \
  -p 443:443 \
  -e WHD_TLS=true \
  -e WHD_TLS_CERT_FILE=/certs/server.pem \
  -e WHD_TLS_KEY_FILE=/certs/server.key \
  ncarlier/webhookd

2. ACME自动证书（需域名）：

bash
docker run -d --name=webhookd \
  -v ${PWD}/scripts:/scripts \
  -v ${PWD}/acme:/acme \
  -p 80:80 -p 443:443 \
  -e WHD_TLS=true \
  -e WHD_TLS_DOMAIN=hook.example.com \
  ncarlier/webhookd

许可证

MIT许可证，详见https://github.com/ncarlier/webhookd/blob/master/LICENSE%E3%80%82