How to configure Webooks to Fluid Boards integration

Webhooks let you subscribe to events happening in a Fluid and automatically receive a delivery of data to your server whenever those events occur.

When an event that your webhook is subscribed to occurs, Fluid will send an HTTP request with data about the event to the URL that you specified. If your server is set up to listen for webhook deliveries at that URL, it can take action when it receives one.

On a Fluid board the events are based on the Actions/Cards that form part of the board. The events supported are Create, Update and Delete. Whenever one of these events occurs on an Action for the board, your webhook will be called. 

TABLE OF CONTENTS

• Access the Integrations option on the board
• Completing the Integration details
• Authentication Provider
  • Shared Secret
  • PAT Tokens
  • Request Parameters
  • Expand Parameters
  • Trigger on Create
  • Trigger on Update
  • Trigger on Delete

Access the Integrations option on the board

To start off, navigate to the integrations options on your board from the the Tools tab. 

Once the Integration options is selected and the dialog opens, you will then be able to select the integration for Action Webhooks.

The following dialog will present the Set Up page where the integration details for the board can be completed. 

You can learn more about how to initially create a board in Fluid by clicking here. 

Completing the Integration details

Each of the sections for the integration details are as follows:

Authentication Provider

Fluid supports Shared secret, PAT tokens or Basic Authentication for access to your webhook url endpoint. Project managers should work with their internal IT teams to provide the information below as part of the setup requirements.

Shared Secret

A shared secret is a signature that is added to the webhook payload that is verified by your organisation on delivery. The secret value is used to sign the payload. Confimation on dellivery will 

You should set a webhook secret for your webhook and verify that the signature of each webhook delivery matches the secret. This helps to ensure that the webhook delivery is from Fluid. For more information, see Validating Webhooks

The webhook secret should be a random string of text with high entropy. You should securely store your webhook secret in a way that your server can access.

NOTE: With respect to permissioning of the Service Principal to the DevOps projects, it is important that the account is also permissioned to the Area level that the project resides in, and not just the project itself. The Service Principal requires access along the hierarchy tree down to the specific project.

The service principal will need to be permissioned to Azure DevOps project(s) you want to integrate with and have the same permissions as a typical user that contributes to the board/worktitems in DevOps.

Details on Service Principals if you need them: https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops#1-create-a-new-managed-identity-or-application-service-principal

PAT Tokens

Below are the required configuration details:

1. PAT token as generated from your DevOps instance

Request Parameters

Define a comma delimited list of fields you want to include as part of the payload for the webhook. eg. if you only want to receive the Title and Description properties of the Action, then use "Title,Description" 

If not set, then a predetermined default list of fields will be used.

Only set values here if you want to streamline the data payload that is sent as part of the webhook request. Reducing payload size will increase performance when parsing results.

Note: Request parameters only apply to the Action Entity itslef.

Expand Parameters

Define a comma delimited list of expandable sections you want to include as part of the payload for the webhook.

Expands are additional properties on the entity object that can be requested. eg CustomProperties, Related, Methods etc. For a full list see http://[organisation].fluid.work/doc

If not set, then predetermined default list of expand sections will be included.

Only set values here if you are interested in the more advanced detailed information for an Action, eg what other actions may share a relationship with this Action, ie child or parent. Show Attachment download details if this action contains attachments. Show all custom properties for this Action etc.

Trigger on Create

Enable this option if you want your webhook URL to be called when a new Action has been created on the board.

Trigger on Update

Enable this option if you want your webhook URL to be called when an existing Action has been changed. ie editied and then saved. Once saved your webhook URL will be called.

Trigger on Delete

Enable this option if you want your webhook URL to be called when an existing Action is deleted.