★ FEATURED ARTICLE 如何配置 WebhookGitHub/GitLab/Slack 多平台配置实战指南【免费下载链接】webhookwebhook is a lightweight incoming webhook server to run shell commands项目地址: https://gitcode.com/gh_mirrors/we/webhook你是否遇到过这样的场景代码一推送到 GitHub就希望服务器自动重新部署GitLab 上有事件就希望即时收到通知在 Slack 里敲个斜杠命令就能触发后台任务。传统做法是写个脚本不停轮询既浪费资源又滞后。而Webhook 配置的思路正好相反——不再是你去问有没有新事件而是事件发生时由对方主动按门铃。本文基于轻量级入站 Webhook 服务器 webhook用于接收 HTTP 回调并执行 shell 命令带你从零配置一套多平台 Webhook覆盖 GitHub Webhook 配置、GitLab Webhook、Slack 集成、HMAC 签名验证、Webhook 安全与常见排错。先用一个比喻看懂 Webhook 是怎么工作的把 Webhook 想象成外卖取餐柜。你webhook 服务器在柜子里放了一个空盒并告诉外卖平台GitHub/GitLab/Slack我的取餐码是这个柜子编号。Webhook 触发流程事件触发你往仓库推了一次代码GitHub 检测到有推送这个事件。HTTP 回调GitHub 把这次推送的信息commit id、分支名、推送人打包成一份 JSON向你预先填好的 URLhttp://yourserver:9000/hooks/你的hook-id发一个 HTTP POST 请求。执行动作webhook 收到请求按你写的trigger-rule校验身份通过后执行execute-command指定的脚本。重点整个过程是你被动接电话而不是主动打电话问。链路就是事件 → 回调 → 执行。理解了这条链下面的配置就只是填参数。配置文件到底在写什么四个核心要素在动手配具体平台前先认识 webhook 的hooks.json里一条记录hook长什么样。每个 hook 对象必须有id和execute-command其余可选字段作用说明id生成访问端点端点为http://yourserver:9000/hooks/你的idexecute-command要执行的命令hook 被触发后跑的脚本command-working-directory命令工作目录脚本以哪个目录为当前路径pass-arguments-to-command把请求值当参数传把 payload/header 等值作为命令行参数pass-environment-to-command把请求值当环境变量传用envname指定变量名pass-file-to-command把请求值落成文件传适合大体积或二进制数据trigger-rule触发/鉴权规则决定什么情况才执行response-message回给对方的消息调用方收到的响应体这里有个贯穿全文的关键概念——请求值引用referencing request values。无论是当参数还是写规则取值都要声明source来源和name字段名常见来源有四种{ source: header, name: X-Hub-Signature } // HTTP 请求头 { source: url, name: token } // URL query 参数 { source: payload, name: pusher.name } // 请求体支持点号取嵌套 { source: string, name: myvalue } // 静态字符串记住这张取值四件套后面每个例子都是在它的基础上组合。下面开始按平台实战。平台实战一GitHub Webhook 完整配置步骤GitHub 的鉴权走HMAC 签名——它用你的 secret 对请求体算一个哈希放进X-Hub-Signature头webhook 用同样的 secret 再算一遍比对。这能保证请求确实来自 GitHub 且没被篡改。适用场景推送代码后自动重新部署且只关心master分支。{ id: webhook, execute-command: /scripts/redeploy.sh, command-working-directory: /var/www, pass-arguments-to-command: [ { source: payload, name: head_commit.id }, { source: payload, name: pusher.name } ], trigger-rule: { and: [ { match: { type: payload-hmac-sha1, secret: mysecret, parameter: { source: header, name: X-Hub-Signature } } }, { match: { type: value, value: refs/heads/master, parameter: { source: payload, name: ref } } } ] } }关键点拆解and表示两个条件必须同时成立HMAC 校验通过且分支是master缺一不可。payload-hmac-sha1用secret比对X-Hub-Signature。注意 2.8 用payload-hmac-sha1旧版本字段叫payload-hash-sha1。pass-arguments-to-command把 commit id 和推送人作为两个参数传给脚本脚本里$1、$2即可拿到。⚠️安全secret必须与 GitHub 后台填的完全一致。如果你的 GitHub 端签名字段同时传了多个逗号分隔webhook 会逐个尝试直到匹配。配好这一条后用curl -v发一个测试请求验证签名逻辑再往下配 GitLab。平台实战二GitLab Webhook 配置要点GitLab 的鉴权方式比 GitHub 简单——它默认给每个 webhook 一个token放在X-Gitlab-Token请求头里。你只要比对这个固定值即可属于共享密钥校验。适用场景GitLab 事件触发部署且只需验证请求来源合法。{ id: redeploy-webhook, execute-command: /scripts/redeploy.sh, command-working-directory: /var/www, response-message: 开始执行部署脚本, pass-arguments-to-command: [ { source: payload, name: user_name } ], trigger-rule: { match: { type: value, value: YOUR-TOKEN, parameter: { source: header, name: X-Gitlab-Token } } } }关键点trigger-rule直接是一个match因为只有一条规则不用and/or包一层直接写最内层匹配对象即可。value类型匹配X-Gitlab-Token头的值等于YOUR-TOKEN就放行。把这里换成 GitLab 后台生成的真实 token。response-messageGitLab 端会收到你自定义的开始执行部署脚本可用于确认请求被接收。技巧和 GitHub 一样你也可以给 token 校验外面再套一层and加上对object_kind事件类型如push或分支的判断实现更细粒度控制。对比一下你会发现GitHub 靠 HMAC 防篡改GitLab 靠 token 防冒用两者思路不同。Slack 又属于第三种形态接下来看。平台实战三Slack 斜杠命令集成Slack 的斜杠命令和上面两个有本质区别它不是签名也不是请求头里的 token而是把 token 直接塞进请求体payload。因为 Slack 用application/x-www-form-urlencoded或 JSON 把表单字段一起 POST 过来token就是其中一个字段。适用场景在 Slack 里敲/deploy后台执行任务并即时返回处理状态。{ id: slack-command, execute-command: /scripts/slack-command.sh, response-message: 正在处理您的请求, trigger-rule: { match: { type: value, value: SLACK-TOKEN, parameter: { source: payload, name: token } } } }关键点source是payload而非header这是 Slack 与前两者最大的差异token 在请求体里所以引用路径是payload.token。response-message尤其重要Slack 命令要求短时间内返回文本用户会直接看到正在处理您的请求否则 Slack 会超时。若任务耗时应配合include-command-output-in-response让 webhook 等命令跑完再返回输出。⚠️安全这个SLACK-TOKEN是唯一的身份凭证务必生成一个足够长且不可猜测的随机串。三种平台鉴权方式对比平台鉴权机制校验位置source / 字段匹配类型适用场景GitHubHMAC-SHA1/256 签名header/X-Hub-Signaturepayload-hmac-sha1等防篡改强校验GitLab共享 tokenheader/X-Gitlab-Tokenvalue请求头固定密钥Slack请求体内 tokenpayload/tokenvalue斜杠命令表单 记忆口诀签名看头header、token 看头、Slack 看体payload。搞清楚 token 放在哪你就不会写错source。进阶能力当 payload 不是普通 JSON前面三个平台发的都是标准 JSON。但真实世界里请求体可能是二进制文件、XML或multipart 表单。webhook 对每种形态都有专门的处理手段下面按数据形态分三类讲。形态一二进制/大文件 → pass-file-to-command当 payload 里有个 base64 编码的文件比如{binary: iVBOR...}直接把整串当参数传会撑爆命令行长度。正确做法是让它落成一个临时文件再把文件路径通过环境变量告诉脚本。{ id: file-handler, execute-command: /bin/ls, command-working-directory: /tmp, pass-file-to-command: [ { source: payload, name: binary, envname: FILE_DATA, base64decode: true } ], include-command-output-in-response: true }base64decode: true先把 base64 解码还原成原始二进制再落盘。envname: FILE_DATA脚本里用$FILE_DATA拿到临时文件路径不写envname则默认用$HOOK_BINARY。临时文件机制webhook 为每次调用生成独立临时文件避免并发互相覆盖执行完默认自动删除。配合include-command-output-in-response: true命令的标准输出会直接返回给调用方方便你curl时立刻看到结果。测试用curl发送jo是生成 JSON 的小工具没有它就手写一个testRequest.json也行jo binary%filename.zip | curl -H Content-Type:application/json -X POST -d - \ http://localhost:9000/hooks/file-handler形态二XML → 节点访问语法有的系统尤其老式接口发的是 XML。webhook 能解析 XML但取值语法和 JSON 不同元素属性用-前缀元素文本用#前缀重复元素按数组下标访问。拿这段 payload 举例app users user id1 nameJeff / user id2 nameSally / /users messages message id1 from_user1 to_user2Hello!!/message /messages /app对应的取值与规则写法{ id: xml-deploy, execute-command: /scripts/deploy.sh, trigger-rule: { and: [ { match: { type: value, parameter: { source: payload, name: app.users.user.0.-name }, value: Jeff } }, { match: { type: value, parameter: { source: payload, name: app.messages.message.#text }, value: Hello!! } } ] } }app.users.user.0.-nameuser出现两次 → 当数组0取第一个-name表示取name属性。app.messages.message.#textmessage只有一个 → 不当数组#text表示取标签内的文本内容。⚠️ 常见坑属性忘了加-、文本忘了加#或该当数组的没加下标都会取不到值。形态三multipart/form-data → 按 part 名解析某些服务典型如 Plex Media Server发的是 multipart 表单一次请求包含多个 part比如payloadJSON 字符串和thumb缩略图。每个 part 靠Content-Disposition里的name标识你通常只关心其中某一个。{ id: plex, execute-command: /scripts/play-command.sh, parse-parameters-as-json: [ { source: payload, name: payload } ], trigger-rule: { match: { type: value, parameter: { source: payload, name: payload.event }, value: media.play } } }parse-parameters-as-json告诉 webhook payload 这个 part 的值其实是一段 JSON 字符串先解码之后就能像普通对象一样用payload.event访问。取值路径变成payload.event因为 JSON 被包在名为payload的 part 下所以前面多了一层payload.前缀。 这个parse-parameters-as-json是通用的请求体里套了一层 JSON 字符串的解法后面排错部分还会再遇到。到这里数据形态各异这个大类就讲完了。但配置写得再对如果没有安全约束端点就可能被陌生人乱触发。下面进入安全红线。Webhook 安全必做清单Webhook 端点本质是一个能被外网触发的命令执行入口安全上必须当高危接口对待。下面用必做 / 不要做两组清单讲清。✅ 必做必配触发/鉴权规则至少加一道校验——HMAC 签名、IP 白名单ip-whitelist或 token 值匹配。绝不裸奔。规则尽量用and组合多重校验例如签名通过 分支正确把攻击面压到最小。IP 白名单用 CIDR{ type: ip-whitelist, ip-range: 192.168.0.1/24 }单 IP 就写/32。敏感值外部化密钥、token 尽量用模板hooks.json.tmpl或环境变量注入而不是明文硬编码进被纳入版本库的文件。最小权限command-working-directory指到受限目录执行脚本用最低必要权限别用 root 跑一切。❌ 不要做不要把密钥写进会被公开的配置/版本库secret 一旦泄露等于把执行权交给别人。不要用 GET query 传密钥当生产方案像?token42这种写法官方明确标注生产环境不安全只适合临时调试。不要忽视反向代理下的 IP 校验webhook 跑在 Nginx/Apache 后面时ip-whitelist看到的是代理的 IP而非真实客户端 IP。这种场景应在反向代理层做 IP 限制而不是依赖 webhook 的白名单。不要给无关事件也执行命令用or/and/not精确圈定事件类型别来者不拒。⚠️一句话Webhook 安全 先验明正身鉴权再限制能做什么最小权限 工作目录 权限降级。排错实录现象 → 原因 → 解法配置上线后最常见的为什么没反应/反应不对基本都集中在 payload 形态和调试上。用问答体把高频问题过一遍。Q1我配了规则但永远不触发payload 明明有那个字段现象按字段名写规则匹配不上。 原因很可能你的JSON 顶层是数组而不是对象。 解法webhook 会把顶层数组塞进一个叫root的对象里所以取值要加root.前缀数组项用下标。比如访问第二个元素的event字段{ source: payload, name: root.1.event }Q2对方系统发来的 payload 是一个JSON 字符串我怎么访问里面的字段现象payload 形如payloadJSON_STRING直接按点号取不到。 原因外层是个字符串不是已解析的对象。 解法用parse-parameters-as-json先把它解码之后才能像普通对象访问parse-parameters-as-json: [ { source: payload, name: payload } ]这正是前面Travis CI / TraCI 类系统的通用解法——它们都把真正的数据当作名为payload的 JSON 字符串包了一层解码后才能取payload.state、payload.branch等。Q3怎么快速确认命令到底跑了没、跑了啥现象端点返回了但不知道脚本内部发生了什么。 原因默认情况下 webhook 不返回命令输出。 解法开include-command-output-in-response: true让 webhook 等命令执行完把原始输出作为响应体返回命令失败则返回 500。加include-command-output-in-response-on-error: true在失败时也带上 stdout/stderr便于定位。调试时用curl -v看完整请求/响应头和状态码确认签名头、分支值是否真的发对了。Q4HMAC 校验一直失败现象payload-hmac-sha1匹配不上。 原因通常是 secret 不一致、或请求头字段名写错、或 payload 被中间环节改过。 解法核对 GitHub 后台 secret 与配置secret逐字符一致确认头名X-Hub-Signature还是X-Signature-256和哈希算法sha1/sha256对应正确检查有无反向代理改写了请求体。排查完这一轮你的多平台 Webhook 基本能跑起来了。收尾webhook 这套方案的适用场景非常明确把轮询换成回调让 GitHub/GitLab/Slack 等外部事件主动触发你服务器上的 shell 命令做自动部署、通知、CI/CD 衔接。最后一遍提醒端点能跑不等于安全——务必配上鉴权规则签名 / token / IP 白名单、把密钥移出明文、并对执行命令做最小权限和工作目录限制。配置细节可参考仓库内 docs/Hook-Definition.md、docs/Hook-Rules.md 与 docs/Hook-Examples.md。把先验明正身、再限制能做这条红线守住你的多平台 Webhook 就能既省心又安全地跑起来。【免费下载链接】webhookwebhook is a lightweight incoming webhook server to run shell commands项目地址: https://gitcode.com/gh_mirrors/we/webhook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
