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.
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:
Name | User friendly name for this integration will be used as part of the HTTP request header User-Agent. It will have the prefix Fluid-Hookshot/{Name} |
Active | Whether integration is currently enabled for this board. |
Webhook Url | The Url endpoint you want Fluid to send requests too. The full Url is required including the http:// or https:// eg https://your.organisation.com/events |
Authentication Provider | See below in the next section. |
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:
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 itself.