• 帮助文档

# Webhook

使用回调钩子，可以在当项目有新推送的代码或缺陷时自动触发 URL。 在推送、缺陷、合并请求、评审事件等，可以配置项目回调钩子来监听事件。当事件发生时，工蜂会向项目回调钩子 URL 发送一个 POST 请求。 回调钩子可以被用来更新问题追踪，更新备份镜像、触发 CI 构建，甚至是在服务器上部署。

# Webhook 使用须知

# SSL 验证

默认情况下，对带https的 url , Webhook 发送时会根据证书颁发机构的内部列表去进行验证，如果接收端不支持https，在 url 中请使用 http

# 超时规则

  • 连接超时时间为2秒：指四层网络层面的连接超时设置，如失败说明与 Webhook 接收端未成功建立网络通道，消息未发出去，故此场景失败会自动重试3 次，重试规则见 下文。
  • 读超时时间为5秒：指 Webhook 接收端收到事件后，工蜂等待返回的最长时间。如果5秒内未能收到接收端的返回信息，则会断开请求。且为避免重复触发，此场景不会重试。作为接收端，请务必保证尽可能快速、简洁地返回，非拦截场景考虑直接做异步返回，避免因为较长的等待时间而导致其他 Webhook 被阻塞。

# 自动重试

工蜂发送事件时，如果遇到连接超时Connect timed out、连接拒绝Connection refused或者 TCP 无响应failed to respond等四层网络异常，最多会自动重试 3 次（每次间隔 100ms）以尽可能规避网络抖动带来的影响，但若最终仍失败，则仅会展示最后一次的请求记录。 故如果遇到上述报错，请先检查下接收端站点的网络是否正常或者是否有网络策略问题。

# 消息大小限制

Webhook 的事件总大小不超过 10MB，超出限制的消息，会被系统丢弃，不会进入发送环节

# 发送失败判定

  • 只有返回的http 状态码为20x的 Webhook，会被视为发送成功
  • 发送超时或者返回非20x的状态码，将被视为发送失败

# 拦截与放通

仅适用于 SVN 的 Pre-xxx 事件 或者 git 的 Pre-Receive 事件

  • 当且仅当 http 响应体 (body)中 status 字段的值为 500 时才会阻止本次推送
  • 超时时间为5s，如果超过 5s 未返回结果，则推送会被判定为通过
{
    message: "Commit not valid, reason: xxxxx",
    status:  500,
}

# 失活与激活

失活统计

  • 上次激活时间未超过48 小时的 Webhook 不做失活统计
  • 最近48 小时发送次数超过20次，且发送失败率超过50%的 Webhook 将被系统设为失活状态
  • 除了“激活测试”外，失活的 Webhook 将无法被任何事件触发

激活

  • 新添加或者修改过 url的 Webhook 默认是失活状态，需要手动激活
  • 在点击激活或者测试按钮后，系统会根据 Webhook 订阅的事件类型，发送测试事件，仅当测试事件全部发送成功，Webhook 的状态会被自动转为活跃
  • 测试事件的内容是工蜂伪造的，并非真实发生的事件，仅用于验证网络连通性，且不保证所有字段都有数据，此类事件的 http header 中X-Source-Type值为Test，在处理具体事件时，建议忽略具有相关特征的事件，并直接返回 http 状态码200以完成激活

# 时效性与事件顺序

  • Webhook 事件可能因为事件内容计算耗时、接收端网络可达性、当前系统繁忙程度等因素，导致存在分钟级的延迟
  • 系统会尽量按照事件发生的顺序来发送 Webhook，但不保证顺序的绝对一致，如果您需要知道该事件相对于另一个事件发生的时间，则应对照 http header 中所包含的时间戳

# 重复的事件

同个 SVN 项目内按不同路径订阅的 Webhook，如果接收端的 url 相同且同时命中了同个事件，则只会触发到路径层级最小的 Webhook，以此避免同个事件在接受端被重复触发。

# Webhook 接收者举例

可以在控制台运行的简单的 echo 脚本进行测试，然后将文件保存为“print_http_body.rb”。

require 'webrick'

server = WEBrick::HTTPServer.new(:Port => ARGV.first)
server.mount_proc '/' do |req, res|
  puts req.body
end

trap 'INT' do
  server.shutdown
end
server.start

选择一个未使用的端口 (例如 8000) 并启动脚本：ruby print_http_body.rb 8000. 然后在工蜂中添加服务器https://my.host:8000/作为 webhook 接收器

在工蜂中按下“测试 Hook”时，正常情况下，会在控制台中看到类似下面的东西。

{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
example.tencent.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0

# Webhook 接收不到的原因

# 系统可用性因素

如果当前系统处于异常状态，可能也会影响 hook 发送或接受，可以通过在设置页面中，点击测试按钮，来验证 hook 是否正常。

lastUpdate: 2/11/2026, 11:37:55 AM

← Git WebHooks →