Webhooks in Jira are responsible for sending updates to Aha! from Jira. Enabling a webhook is essential for establishing two-way communication between the systems.
In Jira, webhooks run at a server level. Typically, only a single webhook needs to be enabled in order to establish two-way updates for all of your integrations. Having multiple webhooks enabled can cause record and event duplication in Aha! when a record is updated in Jira.
However, there are a few situations where multiple webhooks are required.
Situation 1: You need to run the integration with multiple users
When you set up a webhook, all actions in Jira are automatically performed by an Aha! user. The integration is subject to the permissions of this user.
Usually, you want to run the integration as an Aha! user who has access to all products involved in the integration. If no such user exists, you will need to create one with product owner or contributor user permissions. Often, these users are named something like “Jira integration” to let your team determine when the integration is making changes to an Aha! record.
However, in some scenarios, you may need multiple users to manage your Jira integration. In these cases, you will need multiple users with access to different products in Aha! and a separate webhook for each user. Be careful that the users cannot access any of the same products or you will see duplicate Aha! records and events.
Situation 2: You are using both 1.0 and 2.0 Jira integrations
Aha! 2.0 integrations are more powerful and flexible than 1.0 versions. For example, they allow you to map any Aha! field to any Jira field. So we always recommend converting any 1.0 integrations to 2.0 versions.
However, it is possible to use both 1.0 and 2.0 Jira integrations simultaneously. If you are in this situation, you will need to use separate webhooks. A webhook for a 1.0 integration will not update a 2.0 integration.
Situation 3: You want to use complex JQL data filtering
You can add a JQL filter into a Jira webhook to limit the updates sent to Aha! from Jira. In rare scenarios, you may need one webhook to handle certain issue types one way and another webhook to handle other issue types in a different way. In this case, you would need to create multiple webhooks with different JQL filters.
It is rare that you will need this level of complexity, but a hypothetical scenario like this one might warrant it:
You have an integration between Aha! and Jira and you want to create epics, user stories, and sub-tasks in Aha! and send them to your engineering team. You want changes to those issues in Jira to be reflected back in Aha! You also want any new feature user stories that your developers create to flow back to Aha!
However, you do not want some sub-tasks that developers create to flow back up to Aha! You can uncheck the Issue created event for this webhook so no new sub-tasks flow back into Aha!
The solution for managing this process is the creation of two different webhooks, which would look like this:
- Webhook1: JQL = issuetype in (improvement, "New Feature") and Events = <everything including issue created>
- Webhook2: JQL = issuetype in (Epic, "User Story", Sub-task) and Events = <everything other than issue created>