How Aha! webhooks work for Jira Integrations (1.0 and 2.0)

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

There are three key aspects about webhooks to understand:

  1. The webhook runs as a specific Aha! user.
  2. In Jira, the webhook is installed at a global access system level.
  3. Every Jira integration includes its own, unique, webhook.

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.

Point 1: The webhook runs as a specific Aha! user

This is the key to understanding how webhooks function. The webhook runs as a specific Aha! user as identified by the Webhook will run as user: line highlighted in the below screenshot. This means that the webhook inherits that user's ability to write changes to Aha! and can communicate changes from Jira to Aha! for every product the user has Product Owner or Contributor access to.

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

More so, changes that are communicated through the webhook actually appear in Aha! 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 Product Owner or Contributor user to you Aha! account and set the webhook to run as that user. This is a fairly common practice within medium to large size 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! user.
  • The webhook writes changes to Aha! based on that user's access in Aha!
  • The changes written from the webhook appear to as coming from the Aha! 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.

webhook-run-as-user.png

Point 2: 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 listen to activity that occurs across every project in your Jira instance.

While the webhook listens to all activity by default, Jira users have the option to add JQL filters limiting the scope of what the webhook can listen to. 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 more prevalent than others

  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.

webhook_in_jira.png

Point 3: 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! with each integration you setup and assume that each webhook needs to be added to Jira to ensure that each integration functions in a two way workflow.

This is incorrect thinking.

As described in point 1:

  • The webhook runs as a specific Aha! user.
  • The webhook writes changes to Aha! based on that user's access in Aha!
  • 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 product in your entire Aha! 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! account; multiple webhooks lead to multiple sources of the same information communicating back to Aha! -- you will end up with duplicated updates.

This most commonly manifests itself with comments added in Jira.

  • Webhook 1 sees the comment activity and sends it to Aha! where it is written as a comment on the related record in Aha! (Good).
  • Webhook 2 also sees the comment activity and sends it to Aha! where it is also written as a comment on the same record (Not good).

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

  1. From point 1, if no user has global access to every product in Aha!, you may need multiple webhooks.
  2. From point 2, if you intend to do some complex JQL filtering, you may need multiple webhooks.

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

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Powered by Zendesk