TeamCity Webhooks

启用 Webhooks

1. 导航至 Administration | <Root project> | Parameters。

2. 点击 添加新参数 以创建两个 配置参数。

   

   • teamcity.internal.webhooks.enable — 指定是否启用了 webhooks。 将此参数设置为 true。

   • teamcity.internal.webhooks.url — 存储 TeamCity 应向其发送有效载荷的 URL（通过 HTTP POST 请求）。 为了测试目的，您可以指定任何实时网络钩子测试服务提供的 URL，例如 Webhook.site 或 Beeceptor。

3. 指定应触发发送 POST 请求的事件列表。 为了做到这一点，为那些您需要追踪其事件的 TeamCity 项目创建 teamcity.internal.webhooks.events 配置参数。

   下面的列表列出了可用的 teamcity.internal.webhooks.events 参数值。 使用分号（ ; ）作为多个值的分隔符。

   AGENT_REGISTRED

   跟踪事件： 新的构建代理连接到了 TeamCity 服务器并获取了一个 授权令牌。
   父项目： 仅限 <根项目>
   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

4. 执行一个能触发被跟踪事件的动作（例如，运行一个新的构建以触发 构建类型已加入队列 > 已加载更改 > 构建已开始 > 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，以及取消此构建的人的用户名。

授权设置

如果接收方 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。