An incoming webhook/servicehook is a user-defined callback over HTTP. You can use DevOps webhooks/servicehooks to notify Fluid when certain events occur in DevOps. For example, alert Fluid when an work item is created or deleted. Your Fluid board is kept up to date without you having to periodically bulk upload new tasks, or integrate tasks manually.
Servicehook is the DevOps terminology for an industry standard Webhook, these terms are the same and can be used interchangeable in this document. Fluid supports CEATE and DELETE events for DevOps TASK types only at present. Only TASK types that you have configured specifically for your Fluid board for integration will be supported.
Due to the complexity that can be involved with DevOps, by default, incoming servicehooks are not enabled on your client instances, please reach out to your Fluid Success representative who can enable this feature and guide you through the setup process.
TABLE OF CONTENTS
Configuring Fluid
Fluid Authentication Providers
For security, DevOps use basic authentication when sending data to Fluid. This is the only authentication protocol that is supported by DevOps. With respect to Fluid, we use PAT tokens and we validate the username of the account that will be sending the incoming webhook/servciehook events. To learn more about PAT tokens see Creating a Personal Access Token
To configure the username of the account that will be sending messages to Fluid, please follow the steps below.
- Click on your profile top right of Fluid, and select "Administration Console"
Select "Authentication Providers"
- Browse the page and ensure the below option "Allow DevOps Incoming Webhook" is enabled
Enter the username of the account that will be sending the PAT token for authentication. The username as defined under "User management" in fluid. Below is an example for user David Burt, with username david.burt
- When complete, click Save.
Configuring DevOps
DevOps incoming servicehook configuration requires setup to tell DevOps what events and how to send these events to Fluid. Fluid has a HTTP Rest endpoint that can be configured within DevOps.
Please see this article for detailed setup in DevOps. https://learn.microsoft.com/en-us/azure/devops/service-hooks/overview?view=azure-devops and https://learn.microsoft.com/en-us/azure/devops/service-hooks/troubleshoot?view=azure-devops
Registering a servicehook via the DevOps administration console. Please ensure the account you are access DevOps with has the correct admin privileges to setup DevOp servicehooks.
- Go to DevOps projects settings
- Click + To create a Servicehook
- Choose Web hooks on the left navigation and click Next
- Choose "Work item created" on the Trigger on this type of event drop down list if you want to raise create events to Fluid, or "Work item deleted" for deleted events to be raised.
Note: At present only Create and Delete events are supported
Filters:
You can optionally include additional filters to control/limit when these events are raised and sent to Fluid. You should try to limit these events as much as possible to meet your requirements. Each event will trigger Fluid, so only events you want to raise should be included.
- Click Next
Url
This is the Url that DevOps will send information about the item that you have configured. The Url is a specific Fluid Url and will read, validate and action the webhook when a message is received.
To find the Url for your board you need to access the integration configuration for the Fluid Board, See article How to configure Jira to Fluid Boards integration for more information.
Scroll down the integration board configuration page and find the below setting "Allow Incoming Webhooks from DevOps", enable "Allow Incoming Webhooks from DevOps" a textbox will appear, this is the Url you should enter in the above DevOps Url Field.
- Click on the copy to clipboard icon on the right and past into the DevOps UI.
FYI: The last 2 numbers of the Url are the workspace/board identifiers respectively, they represent the workspace (config) and the exact board you want the card to be created on (workspaces can have more than 1 board). In the above examples 692 is the workspace id, (if you click on the @ page you'll see this is the same number on the @ url). The 1108 is the exact board for this workspace. If you know the workspace id and the board id, you can build this url manually to suit your needs.
Basic Authentication
For security purposes Fluid enforces the optional requirement of Basic Authentication when using DevOps Servicehooks. When using basic authentication you setup a Fluid Account that will be used to handle the incoming request from DevOps. This account needs to have the pre-requisite Fluid permissions to Create/Delete Items on the configured board.
Basic Authentication username
- Enter the Fluid username of the account that will be used to handle this request from DevOps.
Note: This username needs to be the same username that was configured in the Fluid authentication providers section of this document. If the usernames are not the same, a HTTP code 401, Unauthorized is returned.
Basic Authentication password
- Enter the PAT token for the Fluid username configured above. You will need to have admin permission to generate a token for different Fluid account. Click on your profile picture top right, and select User Management
- Select the account you want to configure with a PAT token
- Click "Generate Personal Access Token"
- Copy the password string into the Basic Authentication Password textbox.
- You can leave all remaining fields with their default values
- Click Finish to complete this Servicehook.
Note: You will need to follow the same above steps to create a Servicehook for the Delete event, but choose the "Work Item Deleted" when choosing the triggering event.
- Once completed you will see a list of the craated Servicehooks
Further Reading
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article