TeamCity Webhooks
Webhooks are automated HTTP-based messages sent from apps or services when a certain event occurs. Using webhooks, you can set up an event-driven communication between two APIs.
TeamCity can send payloads to the target URL when a new build starts, an agent unregisters, the server collects changes from a remote repository, and more.
Enable Webhooks
Navigate to Administration | <Root project> | Parameters.
Click Add new parameter to create two configuration parameters.
teamcity.internal.webhooks.enable
— specifies whether webhooks are enabled. Set this parameter totrue
.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.
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 available
teamcity.internal.webhooks.events
parameter values. 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/agentAGENT_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/agentAGENT_REMOVED
Tracked Event: A build agent was removed.
Parent Project: <Root project> only
REST API Payload Schema: #/definitions/agentBUILD_STARTED
Tracked Event: A build started. Follows the
BUILD_TYPE_ADDED_TO_QUEUE
andCHANGES_LOADED
events.
Parent Project: Any project.
REST API Payload Schema: #/definitions/buildBUILD_FINISHED
Tracked Event: A build finishes, regardless of whether it failed or was successful.
Parent Project: Any project.
REST API Payload Schema: #/definitions/buildBUILD_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/buildCHANGES_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.
Parent Project: Any project.
REST API Payload Schema: #/definitions/buildBUILD_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/buildBUILD_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
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
.