Bundled Slack WebHook Templates

As of the time of writing (December 2017), there are two Slack specific webhook templates bundled with a tcWebHooks release.

1. The “Slack.com JSON templates” payload format has templates which produce a message in slack with some information about the build.

2. The “Slack.com Compact Notification” has templates which produce a more compact notification.

If neither of those are right for you, it’s possible to create your own template by either copying an existing one, or creating a new one.

WebHook Templates

A WebHook Template is a predefined payload that can be reused with multiple webhook configurations. I’ve prepared a few to get you started, but it’s very easy to modify them or create your own. The ones bundled with tcWebHooks include:

The recent release of TeamCity 9.1 caused an issue with webhooks failing to be sent under certain specific conditions.
The Branch object supplied by TeamCity as part of an sBuild now contains references to the parent project, which then contain references back to the build which contains a reference to the Branch.

This creates a circular reference which prevented the Xstream library from serialising the webhook payload.

This would only present if one was running a build from a VCS that supported branches (Git or HG) and it was a non-master build (eg, feature branch) and the payload was XML or JSON.

I have worked around this by creating a simple bean and copying just the relevant parts of the branch to the bean which is then serialised in the webhook content.

I also found an issue with creating new webhooks in the _Root project. The “create webhook” message was sent to TeamCity when the webhook editing dialog closed, but the new webhook was never actually being created. This has now been resolved.

Currently, sourceforge is preventing me from adding new release files for download.
I therefore, think now is the time to move to GitHub for releases. The updated release (v0.9.35.72) can be downloaded from https://github.com/tcplugins/tcWebHooks/releases

As usual, any issues can be raised on GitHub or posted on the tcWebHooks bugs page.
Additional Feature: Double template rendering passes.
Messages passed to webhooks payloads containing ${variables} are now parsed twice. This means that custom messages can contain tcWebHook variables as requested in a comment on the blog. You can read more in the commit message.

Custom Parameters are a feature in the tcWebhooks plugin, which allow one to send a custom string to the webhook endpoint made up of a template and variables.

Up until today, those variables have only included other values from the webhook’s payload. However, from now on it is also possible to use build paramters from the TeamCity build configuration. One now has access to the TeamCity build properties. These include properties defined by the build configuration, as well as env.*, teamcity.* and system.* properties.

Using the TeamCity build parameters to create Custom Webhook Parameters

Additionally, any property beginning with the string “webhook.” will automatically be included in the webhook payload with the “webhook.” prefix removed. This allows custom parameters to be declared from the Teamcity build parameters rather than having to edit the webhooks plugin XML file. The above example could then be configured as per the following screenshot.

Download the 0.9.26.60 version (or higher) from sourceforge to try it out.

I was recently asked in the comments whether it is possible to add a webhook to trigger for all builds in all projects.

The answer is: yes, but you have to add it to the configuration manually.

The _Root project

In recent versions of TeamCity, a hierarchy was introduced for projects. This means there is now a “Root” project, which is referred to internally by TeamCity as “_Root”. All projects are descendants of the Root project.

When I added descendant project support for the tcWebhooks plugin, I deliberately didn’t allow configuration of the Root project, because it would be too easy to inadvertently add a webhook to every build on TeamCity, even if there are builds that are not your part of a team’s projects.

However, that logic is applied in the UI, not at the webhook triggering level. Therefore, if you configure a webhook in the _Root project XML file on the TeamCity server, it will add a webhook for every build on every project.

Here is a quick example of how to integrate slack.com with TeamCity using the tcWebHooks plugin.

Messages posted to Slack.com from TeamCity using the tcWebHooks plugin.

The first three messages were posted using the first example XML configuration below. The last two are more elaborate and utilise the second XML snippet.

Step by step

Create a new integration in Slack by going to the “Integrations” page.

Scroll to near the bottom and click on the “Incoming WebHooks” button.

Choose a channel to post into and click “Add incoming webhook”. A new integration should be created.

Find the section entitled “Your Unique Webhook URL” copy the URL underneath it including the Token at the end.

Switch to your teamcity web page and create a new WebHook.

Paste in the webhook URL from step 4 into the webhook config.

Choose Name Value Pairs payload format and select your trigger events. I suggest only selecting Successful and Failed. Otherwise you will fill your Slack channel with too many events. You may only want to choose when a build changes state to further reduce noise.

After you’ve saved your webhook config, you need to add the Slack specific payload options by editing the WebHooks configuration file on the TeamCity server. In TeamCity 8 it will be located at: $HOME/.BuildServer/config/projects/<your_project_name>/pluginData/plugin-settings.xml

Find your newly created WebHook and add the following block of XML before the </webhook> tag.

A more complete example

This shows two full webhook XML configurations so you can see the parameter tag in context. If you look closely, you’ll see the first one only applies to build failures, and the second one only applies to build success messages. That is how you can display a different colour and message for different build results.