Aha! Roadmaps | Use webhooks for Jira integrations

The Aha! Roadmaps webhook is what enables updates from Jira to reflect back in your account. Without the webhook, the integration would only be one-way, from Aha! Roadmaps to Jira.

Jira integration webhooks might not be intuitive at first glance, so this article will provide useful details.

There are four key aspects about webhooks to understand:

1. The webhook runs as a specific Aha! Roadmaps user (either an actual person or a user you create for the integration).

2. In Jira, the webhook is installed at a global access system level.

3. Every Jira integration includes its own unique webhook.

4. If you are using both integrations 1.0 and integrations 2.0, you need a separate webhook for each integration type. A webhook for integrations 1.0 will not update integrations configured as integrations 2.0 and vice versa.

Despite point 3, in general, only a single webhook between all Jira integrations is ever needed. This is because of point 1 and point 2 and will be elaborated in detail below.

Click any of the following links to skip ahead:

• The webhook runs as a specific Aha! Roadmaps user

• In Jira, the webhook is installed at a global access system level

• Every Jira integration includes its own unique webhook

The webhook runs as a specific Aha! Roadmaps user

This is the key to understanding how webhooks function. The webhook runs as a specific Aha! Roadmaps user as identified by the Webhook will run as user line highlighted in the screenshot below. This means that the webhook inherits that user's ability to write changes to Aha! Roadmaps and can communicate changes from Jira to Aha! Roadmaps for every workspace where the user has owner or contributor permissions.

If the Aha! Roadmaps user the webhook is running as does not have access to every workspace in your account, the webhook will not be able to correctly write changes from Jira to every workspace in your account. If there are no Aha! Roadmaps users who have full access to every workspace, you may be in one of the few scenarios when multiple webhooks are needed.

Also, changes that are communicated through the webhook actually appear in Aha! Roadmaps as if they are made by the webhook's Run as user. This means that if you want the changes to appear to be written as something other than an actual person at your account, you will need to add another workspace owner or contributor user to your Aha! Roadmaps account and set the webhook to run as that user. This is a fairly common practice within medium to large organizations where they will add a user and name it some variation of "Integration user" so that changes from the webhook appear as being written as "Integration user" instead of an actual person.

The webhook's Run as user can be changed at any time. Simply click the blue Run as me link as highlighted in the below screenshot. Changing the Run as user does not require any changes on the Jira end; the webhook URL itself will remain exactly the same.

In summary:

• The webhook runs as a specific Aha! Roadmaps user.

• The webhook writes changes to Aha! Roadmaps based on that user's Aha! Roadmaps permissions.

• The changes written from the webhook appear as if they came from the Aha! Roadmaps user the webhook is running as.

• The webhook does not solely communicate changes for the integration it belongs to.

• The webhook Run as user can be changed at any time by clicking the Run as me link.

Top

In Jira, the webhook is installed at a global access system level

Webhooks are added to Jira through the system settings. This means that, by default, a webhook added in Jira has the ability to read activity that occurs across every project in your Jira instance. While the webhook reads all activity by default, Jira users have the option to add JQL filters that limit the scope of what the webhook can read. This is highlighted in the below screenshot.

The ability to add the JQL filters provides value in several areas, with two specific use cases being most prevalent.

1. First and foremost, the JQL filtering can be seen as a security feature in that security-conscious Jira administrators can ensure the webhook only transmits activity for the specific projects that are intended to be covered under the integration.

2. Secondly, the JQL filtering can be used to only transmit activity for specific issue types. The below screenshot provides an example of a webhook that is filtered specifically for the Story and Epic issue types. If a Bug in Jira was altered, the webhook would ignore those events due to this filter.

In summary:

• The webhook exists in Jira at a system level.

• The webhook, by default, has global access to activity across all projects in your Jira instance.

• JQL can be used to filter what activity is sent through the webhook.

Top

Every Jira integration includes its own unique webhook

While every integration you create has its own unique webhook, only a single webhook across all integrations needs to be added to Jira except for in specific, infrequent circumstances.

This point can be confusing because it is easy to see the unique webhook in Aha! Roadmaps with each integration you set up and assume that each webhook needs to be added to Jira to ensure that each integration functions in a two-way workflow. However, this is incorrect.

As described in point 1:

• The webhook runs as a specific Aha! Roadmaps user.

• The webhook writes changes to Aha! Roadmaps based on that user's Aha! Roadmaps permissions.

• The webhook does not solely communicate changes for the integration it belongs to.

As described in point 2:

• The webhook exists in Jira at a system level.

• The webhook, by default, has global access to activity across all projects in your Jira instance.

Combining these two together means that a single webhook can pick up activity across your entire Jira account and write that activity to every workspace in your entire Aha! Roadmaps account.

Because of this, multiple webhooks are not only generally incorrect — they can be inherently problematic.

If each webhook can pick up changes across your entire Jira account and write those changes across your entire Aha! Roadmaps account, multiple webhooks lead to multiple sources of the same information communicating back to Aha! Roadmaps, so you will end up with duplicated updates.

This most commonly manifests itself with comments added in Jira, like this:

• Webhook 1 sees the comment activity and sends it to Aha! Roadmaps where it is written as a comment on the related record in Aha! Roadmaps, just like you want it to.

• Webhook 2 also sees the comment activity and sends it to Aha! Roadmaps where it is also written as a comment in Aha!Roadmaps.

There are definitely situations where someone may actually need multiple webhooks.

1. From point 1, if no user has global access to every workspace in Aha! Roadmaps, you may need multiple webhooks.

2. From point 2, if you intend to do some complex JQL filtering, you may need multiple webhooks.

3. From point 4, if you are using both 1.0 and 2.0 integrations in Aha! Roadmaps, you will need two separate webhooks — one for each integration version.

All of these are outlined in detail in our document on when multiple webhooks are needed and why.

Top