Testing a WebHook

Since version 1.1-RC1

It is possible to test a webhook configuration without having to run a build, and even possible to test changes to a webhook before it is saved.

WebHook Testing

Limitations with WebHook Testing

There are some quirks/limitations when testing from the webhooks edit screen, and the template edit screen. Please see the following list for details for behaviour which presents when testing from the UI.

The webhook is executed within the context of a user's request

This means that some variables are resolved by TeamCity. For example, if a build is triggered by the same user as is testing the webhook, the value for the variable ${triggeredBy} will contain the string 'you' rather than the actual username.

A build is in a "finished" state

When a webhook is executed during a normal build cycle, the build is not technically finished. This is because all the event listeners (of which tcWebhooks is one such listener) have not completed. The tcWebHooks event listener receives an instance of the SBuild interface. The implementation class is actually a SRunningBuild instance.

However, when executing a test webhook, the SBuild is represented by an instance of a SFinishedBuild class. SFinishedBuild has a finish time and date set, which a SRunningBuild won't have.

Do not add ${buildFinishTime} to a template, as this will resolve correctly in testing, but fail in a normal webhook execution. If you want to have pseudo "finish time", add a field to your template which has a value of ${currentTime}. Obviously this only makes sense for the finished states (success, failure, fixed, broken). This is how the elasticsearch template works.

Dates and Times don't display consistently

When showing dates in the user's context, TeamCity appears to format java Date objects for display rather than pass the object itself. If you are using dates in a template, don't forget to set the "Date Format" field on the template, so that the template renderer can format the date correctly.

Branch names and TeamCity variables always resolve

When a webhook executes for a buildStarted event as part of a normal build, teamcity has not yet resolved most of the %env.*, %system.* and %teamcity.* variables. Also, the branch name has not been resolved and change information has not been loaded.

However, when executing a test webhook from the UI, the build is in the finished state (see above), and all of these variables will resolve correctly, even if you're testing the buildStarted event.

For this reason, it's often more useful to send a webhook on the changesLoaded event.