TeamCity Webhooks

Webhooks 是当某个特定事件发生时，应用程序或服务发送的基于 HTTP 的自动消息。使用 webhooks，您可以在两个 API 之间设置事件驱动的通信。

TeamCity 可以在新构建开始时，代理注销时，服务器从远程仓库收集更改时等情况下，向目标 URL 发送有效载荷。

启用 Webhooks

导航到管理 | <Root project> | 参数。
点击添加新参数以创建两个配置参数。
- teamcity.internal.webhooks.enable — 指定是否启用了 webhooks。将此参数设置为 true。
- teamcity.internal.webhooks.url — 存储 TeamCity 应向其发送有效载荷的 URL（通过 HTTP POST 请求）。为了测试目的，您可以指定任何实时网络钩子测试服务提供的 URL，例如 Webhook.site 或 Beeceptor。
指定应触发发送 POST 请求的事件列表。为了做到这一点，为那些您需要追踪其事件的 TeamCity 项目创建 teamcity.internal.webhooks.events 配置参数。
以下列表列出了最常用的 teamcity.internal.webhooks.events 参数值。有关可用事件的完整列表，请参阅 Open API Javadoc。使用分号（; ）作为多个值的分隔符。
AGENT_REGISTRED
跟踪事件： 一个新的构建代理已连接到 TeamCity 服务器并获取了授权令牌。
父项目： <Root project> 仅限
REST API 负载架构： #/definitions/agent
AGENT_UNREGISTERED
跟踪事件： 构建代理已停止并与服务器断开连接。当代理软件需要升级或您手动停止代理服务时，可能会发生这种情况。
父项目： <Root project> 仅限
REST API 负载架构： #/definitions/agent
AGENT_REMOVED
跟踪事件： 一个构建代理已被移除。
父项目： <Root project> 仅限
REST API 负载架构： #/definitions/agent
构建已开始
跟踪事件： 开始构建。跟随 构建类型已加入队列 事件。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
BUILD_FINISHED
跟踪事件： 一个构建完成，无论是失败还是成功。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
BUILD_INTERRUPTED
跟踪事件： 运行中的构建已被取消。取消的构建不会触发 BUILD_FINISHED 事件。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
已加载更改
跟踪事件： TeamCity 成功从远程存储库收集了更改（或确认没有新更改）并准备执行构建步骤。根据构建情况，可能发生在 构建已开始 事件之前或之后。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
构建类型已加入队列
跟踪事件： 一个构建已启动并被放入构建队列。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
BUILD_PROBLEMS_CHANGED
跟踪事件： 构建问题列表发生了变化（与同一构建配置的上一次运行相比）。
父项目： 任意项目。
REST API 负载架构： #/definitions/build
执行一个能触发被跟踪事件的动作（例如，运行一个新的构建以触发 构建类型已加入队列 > 已加载更改 > 构建已开始 > BUILD_FINISHED 链），并确保您的目标 URL 收到相应的 POST 请求。

定制请求有效负载

默认情况下，webhooks 会使用完整的 Agent 或 Build 负载发送请求。您可以手动指定应存在于请求有效载荷中的字段。为了做到这一点，添加 teamcity.internal.webhooks.{event_name}.fields 配置参数，其值为 fields=field1，field2，object(field3)。

例如， teamcity.internal.webhooks.BUILD_INTERRUPTED.fields = fields=buildTypeId,number,canceledInfo(user(username)) 参数将仅显示已取消构建的数量，相应构建配置的 ID，以及取消此构建的人的用户名。

{
   "eventType": "BUILD_INTERRUPTED",
   "payload": {
      "buildTypeId": "GhAppMaven_Build",
      "number": "43",
      "canceledInfo": {
         "user": {
            "username": "JohnDoe"
         }
      }
   }
}

  

授权设置

如果接收方 API 不允许匿名发送 POST 请求并需要授权，指定以下额外参数：

teamcity.internal.webhooks.username — 写入 "php-auth-user" 头部的用户名。
teamcity.internal.webhooks.password — 这是写入 "php-auth-pw" 标头的密码。要安全地存储此值并将其从 TeamCity UI 和 REST 请求中隐藏，请在参数设置对话框中点击编辑… 并选择“密码”类型。

重发失败的请求

如果请求未能成功发送（在发送请求时抛出异常，或者接收方的响应代码不是 "2**"），TeamCity 可以尝试重新发送该消息。为了实现这个，创建 teamcity.internal.webhooks.retry_count 参数，并将重试尝试的次数作为其值设定。默认值是 0。

参数继承

TeamCity 项目从其父项目中继承配置参数。例如，如果 <Root project> 具有 teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED 参数，那么每个 TeamCity 项目在其构建开始和结束时都会发送 webhook 消息。

如果父项目和子项目都有一个具有相同名称的参数，那么子项目将覆盖继承的值。例如：

<根项目>包含 teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED 参数；
Project A具有 teamcity.internal.webhooks.events=BUILD_INTERRUPTED 参数。

在这种情况下，所有的 TeamCity 项目都会在它们的构建开始和结束时报告，而 Project A 只报告已取消的构建。如果您需要 Project A 报告所有三种事件，请更改其参数值为 BUILD_STARTED;BUILD_FINISHED;BUILD_INTERRUPTED。

最后修改日期： 2025年 9月 3日