Skip to end of metadata
Go to start of metadata

What

Accxia’s new App WebHooks for Confluence Server brings you another feature your Confluence Server Instance was missing .

This generic App can send Confluence Notifications for any changes in pages, blogposts, comments , related to defined spaces to any 3rd party system what is supporting WebHooks. You even can enable WebHooks for page view events.

Create as many WebHooks as you like, even for different Integrations and Systems.

This document focusses how to integrate with “Mattermost” chat. But you can use it with any other Solutions, what are supporting json WebHooks.


Related Community Requests

https://jira.atlassian.com/browse/CONFSERVER-52487

https://community.atlassian.com/t5/Confluence-questions/Are-WebHooks-available-for-Confluence/qaq-p/382392

https://community.developer.atlassian.com/t/are-webhooks-available-to-add-ons-in-confluence-server/7190

When/Why

If you want to show Confluence Notifications in Mattermost or any other 3rd Party System, simply install and configure the App.

The Mattermost configuration template comes out of the box. For details integrating with Mattermost see

https://docs.mattermost.com/developer/webhooks-incoming.html.


How

This App is only visible for the Confluence Administrator, this is the reason why there is no user documentation.

Install the App from the Marketplace

As for any other App, go to Atlassian Marketplace via UMP and install this App.

Apply a license

You will be redirected to get a trial license as soon as the App has been installed.

Webhooks Configuration

After you have applied the license click the configure button

or click the left Navigation Menu Option


If this option is missing, try to reload the page in your browser.

You will now be redirected to the Configuration Screen

This Screen shows the existing webhooks and some details. We have added the “updated” and “by“ column. So you can easily see who changed webhooks when. By clicking the column headers, you can sort this table.

To create a webhook click the


click …



to edit your webhook


to delete a webHook click


Create/Edit a WebHook


The Configuration Options

Field

Description

Name

Provide a useful name for your WebHook

Active

Check to enable this webhook, do disable uncheck

Note

To exclude any Page or Blogpost from webhook notification, add the label “nowebhook”

Url

The incomming WebHook Url of your target system. This can be any 3rd party system what supports post requests with json payload. See the testing link mentioned for testing, for details see “Testing the WebHook”

Description

A dexription for the purpose of your WebHook

Suppress notification

Do not send notifications for pages protected by view restrictions or when notify watchers is disabled.

SpaceKeys

Add all the Spaces where you want webhooks to be fired. Must be comma separated. Enter “all” to support all confluence spaces.

Authentication

You can add optional basic authentication here, for e.g. Mattermost there is no need to add Basi Auth.

Payload

This is the payload, sent to your web Hook Target Url. It’s structure higly depends on the tagert system. For Mattermost you can load the default template. For details see “The Payload”

Events

Select the related events you are interested in.

To get additional events supported, just contact Accxia, we are happy to help!

The Payload

The payload is sent as the body of the post request. It supports Json data. The content is rendered as the payload when the webhook is fired.

When saving the form data, the App ensures that the payload is valid JSON, otherwise you will not be able to save your data.

The following variables are available and can be used inside the template.

details.action

The action what happened according to the triggered event

details.space

The Space Name

details.actor

The User who triggered the event

details.title

The Titel of the page/blogpost

details.titleLink

The Titel Link of the page/blogpost

details.text

The body of the Page/Blogpost or Comment shortened to 255 characters

details.creatorName

The user who created the content

details.creatorLink

The link to the user who created the content

details.updaterName

The user who updated the content

details.updaterLink

The link to the user who updated the content

details.versionComment

The comment what has been provided while publishing

These variables can be used in the template by entering e.g ${details.updaterName}.

The payload is rendered by using a vm template (velocity). The template for Mattermost looks like


{
    "icon_url": "https://media-exp1.licdn.com/dms/image/C4E0BAQGoaF6RNfEvOQ/company-logo_200_200/0?e=2159024400&v=beta&t=DodxVqmV0MimtX3v9m9MP3fsWkw1tZ7-dkv3j0rPWGk",
    "attachments": [
        {
            "fallback": "${details.action} for ${details.title} in space ${details.space} by ${details.actor}",
            "pretext": "${details.action} in space ${details.space} by ${details.actor}",
            "title": "${details.title}",
            "title_link": "${details.titleLink}",
            "text": "${details.text}",
            "color": "#205081",
            "fields": [
                {
                    "title": "By",
                    "value": "<${details.updaterLink}|${details.updaterName}>",
                    "short": true
                },
                {
                    "title": "Created by",
                    "value": "<${details.creatorLink}|${details.creatorName}>",
                    "short": true
                }
            ]
        }
    ],
    "channel": "Confluence",
    "username": "Confluence"
}

For details see https://docs.mattermost.com/developer/webhooks-incoming.html and https://docs.mattermost.com/developer/message-attachments.html.

Testing your WebHook

We believe you do want to test your webhook before making it productive. In the beginning we tested with requestbin.net. But 1st of all this was not reliable as expected and 2nd you need to make sure not to fire requests containing any passwords or company information.

Thus we decided to implement an own Testing Incomming WebHook Target Url. It is locally available on your System.

If you have installed the App this Url is available for testing under https://<yourbaseurl>/plugins/servlet/webhook/testing.

Just enter this Url as a webhook url e.g, YOU NEED to use your own one, not Accxias:-)


after you defined all details of your webhook, and you will se the last fired webhook at the same url. (This only works for Admins).

It only shows the latest request and does not store/persist any data, it is just kept in RAM and will not persist a Confluence restart.