Jira Incoming Webhooks

Modified on Thu, 13 Feb at 10:07 AM

An incoming webhook is a user-defined callback over HTTP. You can use Jira webhooks to notify Fluid when certain events occur in Jira. For example, alert Fluid when an issue 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.

Fluid only supports CEATE and DELETE events for Jira issue types at present. Only issues types that you have configured specifically for your Fluid board for integration will be supported.

Due to the complexity that can be involved with Jira, by default, incoming webhooks 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
Configuring Jira
Further Reading

Configuring Fluid

Fluid Authentication Providers

For security, Jira uses a shared secret SHA-256 token when sending data to Fluid. This token is validated in Fluid before any further processing will occur, if the shared secret is invalid a HTTP code 401 unauthorized will be return to Jira.

A shared secret is a pass phrase that is only known to Jira and Fluid. Jira will sign the message using the secret pass phrase and Fluid will decode the message, as such Fluid needs to know what the secret pass phrase. The shared secret is configured under the Authentication Providers section of the Admin console. Only a user with administrator role privileges will be able to set this up.

Note: Shared secrets are stored securely in the Azure Keyvault and can only be access by Fluid.

- Click on your profile top right of Fluid, and select "Administration Console"

- Select "Authentication Providers"

- Browse the page and ensure the below option "Allow Jira Incoming Webhook" is enabled

- Enter the shared secret value/pass phrase in the textbox as shown above, you can click on the eye on the right to show/hide the value accordingly.

Note: You should adhere to your organisations internal policy for password/pass phrase length and character types when selecting a shared secret. Fluid does not enforce any rules for shared secrets as each organisation is different.

- When complete, click Save.

Configuring Jira

Jira incoming webhook configuration requires setup to tell Jira what events and how to send these events to Fluid. Fluid has a HTTP Rest endpoint that can be configured within Jira.

Please see this article for detailed setup in Jira. https://developer.atlassian.com/server/jira/platform/webhooks/

Registering a webhook via the Jira administration console. Please ensure the account you are access Jira with has the correct admin privileges to setup Jira webhooks

- Go to Jira administration console > System > Webhooks (in the Advanced section). You can also use the quick search (keyboard shortcut is .), then type 'webhooks'.

- Click Create a webhook.

Name

Give the webhook a name that allows you to identify what the purpose of the webhook and what fluid board/project this webhook is intended to be used for. Depending on your use case, you may require multiple webhooks configured and a good naming convention helps manage these.

Url

This is the Url that Jira 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, enable "Allow Incoming Webhooks from Jira" a textbox will appear, this is the Url you should enter in the above Jira Url Field.

- Click on the copy to clipboard icon on the right and paste into the Jira 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 652 is the workspace id, (if you click on the @ page you'll see this is the same number on the @ url). The 701 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.

Shared Secret

This is the shared secret as configured in the "Fluid Authentication Providers" as found in the "Configuration Fluid" section of this document. The shared secret needs to be the exact same value as configured in Fluid.

- Copy and past both values to ensure they are an exact match.

Events

This is where you configure what events that occur in Jira will be sent to Fluid. The JQL part of the UI is where you configure any rules/queries that will match and trigger the webhook, see here for more detail from Atlassian https://developer.atlassian.com/server/jira/platform/webhooks/

Note: At present Fluid only supports CREATE and DELETE events from Jira

In the below query, as an Example, we have configured a query where project = "Fluid Product", and enabled under the "Issue" column, "create" and "deleted" only.

This means that any issue created or deleted in the Jira project "Fluid Product" will also send a message to Fluid at the Url previously configured.

You are free to write any JQL query you want to fine tune when Jira will sent the messages to Fluid, but you should follow guidelines as set out by https://developer.atlassian.com/server/jira/platform/webhooks/. Please ensure you read through Atlassians documentation thoroughly.

- Click Save when complete.

Now whenever a Jira Issue is created, that matches your JQL query, Jira will send information to Fluid on that item. Fluid will then create the card on the board as specified by the Url configured.