Webhook Parameters
A webhook parameter is a variable that can be included in a webhook payload or URL. This can be either a legacy payload, or a templated payload. Parameters can contain other variables, and resolution will be attempted when the payload is assembled.
There are three ways to define a parameter:
- Webhook Project Parameter (recommended)
- TeamCity build or project parameter
- Webhook configuration
<parameter/>defined when manually editing a webhook inplugin-settings.xml.
Since tcwebhooks 1.2 alpha 8
Requires TeamCity 2017 or later
Webhook Project Parameters are a way to define a parameter for a project and are inherited by all sub-projects (unless redeclared).
They are similar to TeamCity Parameters, but with the following extra features:
- Are available to Build Finished events.
- Can be hidden from legacy payloads.
- Can resolve nested parameters using the standard or velocity template formats.
- Are all available as webhook parameters. No need to prefix them with
webhook. - When marked as Password parameters, they will be externalised by TeamCity and not included in project configuration. Eg, when storing project configuration in VCS.
- Scoped to the project in which they are defined and any sub-projects. Can be used by any webhook as long as the running build is in the same scope as the parameter.
TeamCity Parameters are presented in the TeamCity UI. They're a quick and easy way to create a variable for use in a webhook payload. Note: Teamcity parameters are not recommended for storing sensitive values for use with webhooks because the actual value is masked in Build Finished events, and is therefore not available to tcWebHooks.
All TeamCity Parameters are available as webhook variables by referencing their full name, or they can defined with a webhook. prefix. For example: the parameter webhook.url will be available as both ${url} and ${webhook.url}. The value will also be inserted into a map of parameters as url. The map of parameters is really only of historical significance. Early versions of the tcWebHooks plugin simply returned this map as the payload and the prefix was a way of signifying that the url should be in the payload. Since 1.1, tcWebHooks has supported templating, and the payload can be completely managed in that manner. See WebHook-Templates.
To create a TeamCity Parameter, edit any project or build configuration and select the Parameters section.
TeamCity Parameters are scoped to the Project or Build configuration in which they are defined.
Insert screen shot here
TeamCity Parameters are a quick and convenient way to create a variable for use with webhooks, however be aware that the password type of parameter is obscured in the build finished stage. Therefore it's not possible to use a TeamCity Parameter to store hidden values that you want to use in a webhook.
For more information on passing passwords and token to webhooks see Hiding-Sensitive-Values-In-WebHook-Configuration.
Configuration parameters are the original way of defining parameters, and are stored in the webhook configuration in plugin-settings.xml.
They have always existed, but have been difficult to edit as they require the ability to modify the project's plugin-settings.xml on the TeamCity server.
Configuration parameters use the standard template to resolve variables, and all parameters are included in all legacy payloads.
Configuration parameters are scoped to the webhook in which they are defined. They are not available to other webhooks.
<webhooks ...>
<webhook ...>
<parameters>
<param name="color" value="red" />
<param name="notify" value="1" />
</parameters>
</webhook>
</webhooks>
Note: Since tcwebhooks 1.2 alpha 9, parameters, filters, and headers have been editable in the UI if the tcwebhooks REST API plugin is installed.
Also, the configuration parameters have been enhanced to support the options available to Webhook Project Parameters.