Skip to content

Advanced Editing of tcWebHooks configuration

Jump to bottom Edit New page
netwolfuk edited this page Jun 8, 2017 · 13 revisions

Not all features are editable in the UI yet but can be configured by editing the webhooks element within a project's plugin-settings.xml file.

The plugin-settings.xml file is located in _BuildServer_/config/_Project_Name_/plugins/plugin-settings.xml and contains all the plugins settings TeamCity wishes to store for a project. This file is managed by TeamCity and TeamCity will auto-reload it a few seconds after it is edited on disk. Changes made to webhooks in the UI will also be persisted to this file a few seconds after clicking save.

The following features must be hand-edited.

  • authentication - (since 0.9.80.83 and 1.1-alpha5.81.121) This is ability of tcWebHooks to provide credentials when POSTing to a webhook endpoint. Currently only tested with Basic Auth. Now editable in the UI (since 1.1-alpha8.140.143)
  • trigger-filters - (since 1.1-alpha7.122.138) Filter a webhook so that it only fires if a regular expression is matched. Supports multiple filters which all must match.
  • parameters - A way to define extra parameters which get sent as part of the webhook payload. Note: It's also possible to define parameters by creating "build properties" for a build in teamcity with the prefix webhook., eg: webhook.color=red

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
    <webhook url="http://localhost:58001/200" enabled="true" format="jsontemplate" template="elasticsearch">
      <states>
        <state type="buildStarted" enabled="true" />
        <state type="changesLoaded" enabled="true" />
        <state type="beforeBuildFinish" enabled="true" />
        <state type="buildFinished" enabled="true" />
        <state type="buildBroken" enabled="false" />
        <state type="buildInterrupted" enabled="true" />
        <state type="buildSuccessful" enabled="true" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFailed" enabled="true" />
        <state type="responsibilityChanged" enabled="true" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
	    <param name="color" value="red" />
	    <param name="notify" value="1" />
      </parameters>
      <trigger-filters>
            <filter value="${branchDisplayName}" regex="^branch-xyz$" enabled="true"/>
            <filter value="${buildInternalTypeId}" regex="^bt\d$" enabled="true"/>
      </trigger-filters>
      <auth type="userpass" enabled="true">
       	    <auth-parameters>
                    <param name="username" value="user1" />
                    <param name="password" value="user1pass" />
                    <param name="realm" value="TestRealm" />
            </auth-parameters>
      </auth>
    </webhook>
  </webhooks>
</settings>

Examples of webhook settings in practice

This section lists some real-life examples of how the webhooks and their advanced settings can be used.

BitBucket webhooks (using authentication)

BitBucket offers webhooks for submitting build results for each commit. This requires the tailoredjson format and HTTP Basic Authentication. Since their REST API doesn't return a 401 when the authentication credentials are submitted but will immediately return a 403, we also need pre-emptive authentication.

Some settings aren't directly accessible from the webhook and thus need to be passed through configured parameters on the project itself. These are:

  • webhook.key = %system.teamcity.buildType.id%
  • webhook.name = %system.teamcity.buildType.id%
  • webhook.project = %system.teamcity.projectName%
  • webhook.revision = %system.teamcity.projectName%
  • webhook.url = https://your.teamcity.url/viewLog.html?buildNumber=%system.build.number%&tab=buildResultsDiv&buildTypeId=%system.teamcity.buildType.id%

The webhook for successful builds is included below. The configuration for failed builds has only two differences:

  • Set buildSuccessful to false, buildFailed to true
  • In the JSON contents, change SUCCESSFUL to FAILED 
<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
    <webhook url="https://api.bitbucket.org/2.0/repositories/organization/${project}/commit/${revision}/statuses/build" enabled="true" format="tailoredjson" template="none">
      <states>
        <state type="buildBroken" enabled="false" />
        <state type="buildInterrupted" enabled="false" />
        <state type="buildSuccessful" enabled="true" />
        <state type="buildFailed" enabled="false" />
        <state type="changesLoaded" enabled="false" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildStarted" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="beforeBuildFinish" enabled="false" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
        <param name="body" value="{&quot;state&quot;: &quot;SUCCESSFUL&quot;, &quot;key&quot;: &quot;${key}&quot;, &quot;name&quot;: &quot;${name}&quot;, &quot;url&quot;: &quot;${url}&quot;, &quot;description&quot;: &quot;${buildStatus}&quot;}" />
      </parameters>
      <auth enabled="true" type="userpass" preemptive="true">
        <auth-parameters>
          <param name="password" value="password" />
          <param name="username" value="organization" />
        </auth-parameters>
      </auth>
    </webhook>
  </webhooks>
</settings>

Slack notifications about production deployments (using trigger filters)

This webhook is used to notify a certain group of people when specific build configurations have run. An example is when a deployment configuration is used to deploy to your production environment, which you want to be notified of in case it ever gets triggered when it shouldn't.

In this webhook, the trigger filter is configured to only launch the webhook if the branch name is production. Triggering this build configuration on other branches (e.g. master or staging) will not launch the webhook.

Some settings aren't directly accessible from the webhook and thus need to be passed through configured parameters on the project itself. These are:

  • webhook.branch = %teamcity.build.branch%
  • webhook.key = %system.teamcity.buildType.id%
  • webhook.name = %system.teamcity.buildType.id%
  • webhook.project = %system.teamcity.projectName%
  • webhook.revision = %system.teamcity.projectName%
  • webhook.url = https://your.teamcity.url/viewLog.html?buildNumber=%system.build.number%&tab=buildResultsDiv&buildTypeId=%system.teamcity.buildType.id%

The webhook for successful builds is included below. The configuration for failed builds has only three differences:

  • Set buildSuccessful to false, buildFailed to true
  • In the payload JSON, change deployment OK to deployment failed
  • In the payload JSON, change the color string #00ff00 to #ff0000 
<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
    <webhook url="https://hooks.slack.com/services/..." enabled="true" format="nvpairs" template="none">
      <states>
        <state type="buildBroken" enabled="false" />
        <state type="buildInterrupted" enabled="false" />
        <state type="buildSuccessful" enabled="true" />
        <state type="buildFailed" enabled="false" />
        <state type="changesLoaded" enabled="false" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildStarted" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="beforeBuildFinish" enabled="false" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
        <param name="payload" value="{&quot;attachments&quot;: [{&quot;color&quot;: &quot;#00ff00&quot;, &quot;title&quot;: &quot;${project} (${branch}): deployment OK&quot;, &quot;fields&quot;: [{&quot;title&quot;: &quot;Config&quot;, &quot;value&quot;: &quot;${name}&quot;, &quot;short&quot;: true},{&quot;title&quot;: &quot;Build ID&quot;, &quot;value&quot;: &quot;&lt;${url}|#${buildid}&gt;&quot;, &quot;short&quot;: true},{&quot;title&quot;: &quot;Result&quot;, &quot;value&quot;: &quot;${buildStatus}&quot;, &quot;short&quot;: false},{&quot;title&quot;: &quot;Commit&quot;, &quot;value&quot;: &quot;${revision}&quot;, &quot;short&quot;: false}]}]}" />
      </parameters>
      <trigger-filters>
        <filter value="${branchDisplayName}" regex="^production$" enabled="true" />
      </trigger-filters>
    </webhook>
  </webhooks>
</settings>

Pushover notifications about production deployments (using trigger filters)

This webhook is used to notify a certain group of people when specific build configurations have run. An example is when a deployment configuration is used to deploy to your production environment, which you want to be notified of in case it ever gets triggered when it shouldn't.

In this webhook, the trigger filter is configured to only launch the webhook if the branch name is production. Triggering this build configuration on other branches (e.g. master or staging) will not launch the webhook.

Some settings aren't directly accessible from the webhook and thus need to be passed through configured parameters on the project itself. These are:

  • webhook.branch = %teamcity.build.branch%
  • webhook.key = %system.teamcity.buildType.id%
  • webhook.name = %system.teamcity.buildType.id%
  • webhook.project = %system.teamcity.projectName%
  • webhook.revision = %system.teamcity.projectName%
  • webhook.url = https://your.teamcity.url/viewLog.html?buildNumber=%system.build.number%&tab=buildResultsDiv&buildTypeId=%system.teamcity.buildType.id%

The webhook for successful builds is included below. The configuration for failed builds has only two differences:

  • Set buildSuccessful to false, buildFailed to true
  • In the title parameter, change deployment OK to deployment failed 
<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
        <webhook url="https://api.pushover.net/1/messages.json" enabled="true" format="nvpairs" template="none">
      <states>
        <state type="buildBroken" enabled="false" />
        <state type="buildInterrupted" enabled="false" />
        <state type="buildSuccessful" enabled="true" />
        <state type="buildFailed" enabled="false" />
        <state type="changesLoaded" enabled="false" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildStarted" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="beforeBuildFinish" enabled="false" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
        <param name="message" value="&lt;b&gt;Config:&lt;/b&gt; ${name}&#10;&lt;b&gt;Result:&lt;/b&gt; ${buildStatus}&#10;&lt;b&gt;Commit:&lt;/b&gt; ${revision}&#10;&lt;b&gt;Build ID:&lt;/b&gt; #${buildid}" />
        <param name="title" value="${project} (${branch}): deployment OK" />
        <param name="token" value="sending_token" />
        <param name="user" value="receiving_token" />
        <param name="html" value="1" />
      </parameters>
      <trigger-filters>
        <filter value="${branchDisplayName}" regex="^production$" enabled="true" />
      </trigger-filters>
    </webhook>
  </webhooks>
</settings>
Add a custom footer
Clone this wiki locally