Introduction

Let’s dive deeper into webhooks after we introduced the Jira REST API in a previous blog post.  Organizations use different applications for different purposes, such as Jira for software development, Salesforce for customer relationship management, etc. Oftentimes, there is a need for these applications to integrate with each other. Traditionally, custom development will be needed to create these integrations. However, for many simple use cases, such as updating a record in one application as a result of a change in another application, the traditional approach of writing custom code to use APIs can be too much overhead, and this is where webhook comes in, as a quick, simple, and effective alternative.

‍

‍

What is a webhook?

A webhook is a mechanism that allows for lightweight, event-driven communication between two applications, usually based on the HTTP/HTTPS protocol. It is sometimes referred to as an event-based API, as webhooks are usually triggered by events such as a user action and then react to that trigger by sending a request to a URL endpoint, which can be a REST API.

Some of the key benefits of webhooks are:

• Lightweight—Webhooks are easy to use and configure. Unlike working with APIs, which often require some level of technical and programming knowledge, webhooks often only require a very basic understanding of how the web works, with little to no programming knowledge required.
• Real-time—Because webhooks are event-driven, events are triggered. This allows data and communication to be exchanged between different applications in real-time, as opposed to something like a polling mechanism, which happens based on a pre-defined schedule.

There are two types of webhooks: incoming and outgoing.

Incoming webhook

An incoming webhook sometimes referred to as an inbound webhook, listens to other applications to make incoming calls, hence the name. It usually exposes an HTTP endpoint, and once it receives an incoming request, it processes the request and performs its functions, such as creating or updating records in the local application.

Outgoing webhook

An outgoing webhook, sometimes referred to as an outbound webhook, makes outbound HTTP requests to other systems and applications. It often waits for a trigger, such as when an issue is created or updated in Jira, and then requests a specific URL. The URL would usually be a REST API endpoint, but it can be any valid URL that is accessible by the webhook.

‍

Working with webhook in Jira

Jira (both Cloud and Data Center) supports both incoming and outgoing webhooks via the Automation feature. Jira does have a classic version of webhooks, but it is less intuitive and flexible to work with, so we will be using the newer and more advanced Automation alternative.

In this blog post, we will create an outgoing webhook in Jira to call a REST API in Aha! whenever an issue is created. For those who are not familiar with it, Aha! is a popular ideation and roadmap tool. Many organizations use Jira and Aha! together, and this will be a great example of how we can use webhooks to create an integration between the two applications without writing a single line of code.

Getting an API key from Aha!

The first step we need is to get an Aha! API key that we can use to authenticate our requests to Aha!'s REST API:

1. Go to your Aha! instance and go to Settings -> Developer.
2. Click on the Generate API key button and enter a name for the new API key. You should give it a descriptive name, such as Jira Webhook Example.

‍

‍

3. Once the API key is created, it will be displayed on the page. Copy that API key and store it somewhere safe, as you will not be able to see it again. If you lose it, you will need to generate a new API key.

With the API key created, we can use it to make authenticated REST API calls to Aha! In the next section, we will create the outgoing webhook in Jira that automatically creates new Features in Aha! whenever a new issue is created in Jira.

Setting up automation trigger in Jira

Now that we have Aha! 's API key, we can start creating our outgoing webhook in Jira to call Aha!'s REST API.

1. Log into your Jira (either Cloud or Data Center) as an administrator.
2. Go to the Systems section and then Global Automation.
3. Click on the Create rule button to create a new automation rule that will include our outgoing webhook.
4. The first step when creating an automation rule is to set the trigger for what and when it should execute. In our case, we will set the trigger to be whenever an issue is created, so we select the Issue-created trigger.

‍

‍

5. With our trigger set, the next step is to add an action when the trigger fires, so we select the THEN: Add an action option.

‍

‍

6. Now, we need to select the action we want to perform. In our case, we want to create an outgoing webhook, i.e., make an outbound call to another application (e.g., Aha!). So, we select the Send web request action.

‍

‍

7. Now that we have added our outgoing webhook (action), we need to configure it so it knows what to do. Generally, with outgoing webhooks, you need to tell it the following:

• Web request URL—the URL for the webhook to call. This will also be the URL for the Create a feature REST API.
• HTTP method—An HTTP URL often has a method, such as GET, POST, PUT, etc. For this API, it is POST.
• Web request body—For POST and PUT calls, some data, usually JSON, is sent to the target system. In our case, it will be the Jira issue data we send to Aha!. The request body can include dynamic content, such as the user who triggered it or the issue being created.

We will be using the Create a feature REST API from Aha!, and the API expects a JSON payload, such as below. We are also using Jira’s smart value to automatically populate the payload with the Jira issue’s summary and description values:

‍

‍

‍

Since this REST API also needs authentication, we need to pass in the API key we created early by adding a custom HTTP header called Authorization with the value of Bearer YOUR_API_KEY.

8.  After we configure our outgoing webhook, click on the Turn on rule button at the top and give your rule a name, such as Create features in Aha! 

And this is it. Now, we have an outgoing webhook that will be triggered whenever an issue is created. It will automatically create a new Feature in Aha! based on the values of the Jira issue that triggered it, as shown below. We can extend this use case further by adding another webhook to be triggered when issues are updated in Jira, and we will update the corresponding Aha! features to keep records in both systems in sync.

‍

Summary

Webhook is an easy way to create integrations between different applications by reacting to user actions and sending data between them. Jira supports both incoming webhooks that can listen for requests from other applications and outgoing webhooks that can make requests to other applications. We looked at an example of integrating Jira and Aha! by using webhooks, but you can do so much more with it.

For example, you can leverage webhooks to send status messages to Slack whenever something happens in Jira. In future articles, we will look at more examples of how you can automate processes such as this with Jira Automation, webhooks, and REST APIs.