WebHook Templates : An Introduction

Since tcWebHooks 1.1.x.x

• WebHook-Templates-:-Web-UI
• WebHook-Templates-:-Anatomy-of-a-Template
• WebHook-Templates-:-Creating,-Reading,-Editing,-Deleting
• WebHook-Templates-:-The-Velocity-Templating-Engine
• See also: Webhook-Parameters

WebHook Templates

A WebHook Template is a way of packaging up a set of payloads together, and indicating which events apply to which payload. The template can then be referenced by any number of webhooks, and the relevant payload is chosen depending of the build event as it executes.

WebHook Templates are:

• More readable than parameters or XML encoded strings
• Easy to edit
• Re-usable (DRY)
• Easy to export and import
• Shareable

WebHook Template Rational

WebHook Templates are a way to create a standard webhook payload, and use it across multiple webhooks. For example, to publish build results into a chat systems like HipChat, Slack, Flowdock, Stride, MS Teams etc needs a fairly specific payload. In fact, nearly every service you may want to send a webhook to, will be require a specific format. Setting up a webhook with different message content for different build states is fairly arduous using the standard webhook configuration.

A typical webhook payload

Here is an example payload for Slack which produces a fairly compact message in a chat channel.

{
    "text" : "${buildName} FAILURE",
    "attachments" : [{
            "pretext" : "${buildName} ${projectId}",
            "fallback" : "${buildName} SUCCESS",
            "title" : "Build Log #${buildNumber}",
            "title_link" : "${buildStatusUrl}&tab=buildLog",
            "color" : "danger"
        }
    ]
}

The above message is specific to failure, and has the colour "DANGER" (which is a colour according to Slack).

This is a message for success:

{
    "text" : "${buildName} SUCCESS",
    "attachments" : [{
            "pretext" : "${buildName} ${projectId}",
            "fallback" : "${buildName} SUCCESS",
            "title" : "Build Log #${buildNumber}",
            "title_link" : "${buildStatusUrl}&tab=buildLog",
            "color" : "good"
        }
    ]
}

Again, a fairly specific message, and one that would only apply to a webhook configured to notify for successful events. To implement this in a classic webhook, would require creating two webhooks. One for failure, and one for success. Then each of these would require the payload encoded to XML and manually added to the webhook configuration, or - if using TailoredJSON - a build property created for both message types.

If you wanted to implement the other build events as well (Build Started, Build Fixed, Build Interrupted, Build Responsibility Changed, Build Almost Completed, Changes Loaded, Build Broken) and provide specific payloads for each build event, it would require creating a further seven webhooks. Each of which would need to be manually edited to add the required payload. This quickly becomes cumbersome to create and manage.