TeamCity Webhooks

Enable Webhooks

1. Navigate to Administration | <Root project> | Parameters.

2. Click Add new parameter to create two configuration parameters.

   

   • teamcity.internal.webhooks.enable — specifies whether webhooks are enabled. Set this parameter to true.

   • teamcity.internal.webhooks.url — stores the URL to which TeamCity should send payloads (via HTTP POST requests). For testing purposes, you can specify the URL provided by any real-time webhook testing service, such as Webhook.site or Beeceptor.

3. Specify the list of events that should trigger sending POST requests. To do this, create the teamcity.internal.webhooks.events configuration parameter for those TeamCity projects whose events you need to track.

   The list below enumerates most frequently used teamcity.internal.webhooks.events parameter values. For the full list of available events, see the Open API Javadoc. Use a semicolon (;) as a separator for multiple values.

   AGENT_REGISTRED

   Tracked Event: A new build agent connected to the TeamCity server and obtained an authorization token.

   
   

   Parent Project: <Root project> only

   
   

   REST API Payload Schema: #/definitions/agent

   AGENT_UNREGISTERED

   Tracked Event: A build agent stopped and disconnected from the server. This can happen when an agent software needs an upgrade or when you manually stop the agent service.

   
   

   Parent Project: <Root project> only

   
   

   REST API Payload Schema: #/definitions/agent

   AGENT_REMOVED

   Tracked Event: A build agent was removed.

   
   

   Parent Project: <Root project> only

   
   

   REST API Payload Schema: #/definitions/agent

   BUILD_STARTED

   Tracked Event: A build started. Follows the BUILD_TYPE_ADDED_TO_QUEUE event.

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

   BUILD_FINISHED

   Tracked Event: A build finishes, regardless of whether it failed or was successful.

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

   BUILD_INTERRUPTED

   Tracked Event: A running build was canceled. Canceled builds do not trigger the BUILD_FINISHED event.

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

   CHANGES_LOADED

   Tracked Event: TeamCity successfully collected changes from a remote repository (or ensured no new changes are present) and is ready to execute build steps. Depending on the build, may occur before or after the BUILD_STARTED event.

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

   BUILD_TYPE_ADDED_TO_QUEUE

   Tracked Event: A build was initiated and placed in the build queue.

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

   BUILD_PROBLEMS_CHANGED

   Tracked Event: The list of build problems changed (compared to the previous run of the same build configuration).

   
   

   Parent Project: Any project.

   
   

   REST API Payload Schema: #/definitions/build

4. Perform an action that triggers tracked events (for instance, run a new build to trigger the BUILD_TYPE_ADDED_TO_QUEUE > CHANGES_LOADED > BUILD_STARTED > BUILD_FINISHED chain) and ensure your target URL receives corresponding POST requests.

Customize Request Payloads

By default, webhooks send requests with full Agent or Build payloads. You can manually specify the fields that should be present in request payloads. To do so, add the teamcity.internal.webhooks.{event_name}.fields configuration parameter with fields=field1,field2,object(field3) as its value.

For example, the teamcity.internal.webhooks.BUILD_INTERRUPTED.fields = fields=buildTypeId,number,canceledInfo(user(username)) parameter will display only a number of a canceled build, an ID of the corresponding build configuration, and a username of the person who canceled this build.

Authorization Settings

If the recipient API does not allow sending POST requests anonymously and requires authorization, specify the following additional parameters:

• teamcity.internal.webhooks.username — the username written to the "php-auth-user" header.

• teamcity.internal.webhooks.password — the password written to the "php-auth-pw" header. To store this value securely and hide it from TeamCity UI and REST requests, click Edit... in the parameter settings dialog and select the "Password" type.

  

Resend Failed Requests

If a request was not delivered (an exception was thrown while sending a request, or a recipient response code was other than "2**"), TeamCity can try resending this message. To do this, create the teamcity.internal.webhooks.retry_count parameter and set the number of retry attempts as its value. The default value is 0.

Parameter Inheritance

TeamCity projects inherit configuration parameters from their parent projects. For instance, if the <Root project> has the teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED parameter, every TeamCity project will send webhook messages when their builds start and finish.

If a parent and a child projects both have a parameter with the same name, the child project overrides the inherited value. For instance:

• <Root project> has the teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED parameter;

• Project A has the teamcity.internal.webhooks.events=BUILD_INTERRUPTED parameter.

In this case, all TeamCity projects report when their builds start and finish, while Project A reports only canceled builds. If you need Project A to report all three events, change its parameter value to BUILD_STARTED;BUILD_FINISHED;BUILD_INTERRUPTED.