Webhook Integration with OAuth v2

Purpose

This document provides instructions on adding a Webhook integration, a process applicable to both Outscan and HIAB. For illustrative purposes, we use Jira Cloud as an example of a Webhook integration utilizing OAuth. This guide aims to simplify the integration process and enhance clarity in setting up Webhook integrations within the Outscan and HIAB environments.

Introduction

OAuth V2 capability has been incorporated into Webhook integration within the Portal and REST API. Jira Cloud facilitates external application integration by supporting the OAuth v2 option. This capability enables secure and seamless integration with external applications using the OAuth v2 protocol.

Requirements

An external system implementing OAuth v2 is required.

Set up OAuth Webhook Integration

The process involves the following steps:

Create an application with OAuth 2.0 on the third-party entity (e.g., Jira Cloud). Refer to the example provided below for Jira Cloud for guidance.

Set up the callback URL:
1. For Integration from Outscan:
  1. Callback URL: https://outscan.outpost24.com/portal/oauth
2. For Integration from HIAB:
  1. Callback URL: https//<HIABHostName|HIABIPAddress>/portal/oauth
    Set to HIAB hostname when defined; otherwise, use the HIAB IP address.
Login to either OUTSCAN or HIAB
1. Go to Portal > Configuration > Integrations view.
2. Create a Webhook integration by filling in the required parameters and click Save. See Integration Management for more information.
3. Reopen the newly created integration and navigate to the Authentication tab, select OAuth and fill in the required and optional parameters then and click Save.
4. Once saved, run the authorize call flow by clicking on AUTHORIZE, follow the directions and grant access to resources.
5. Once authorized, go to SETTINGS tab and click on VERIFY.

Create Webhook Integration

To add a new integration, follow these steps:

Click on the green button located in the lower-right corner of the browser window.
Select the desired integration configuration type from the drop-down menu.
Fill in the necessary parameters. See Webhook fields overview.
Click Add to finish creating the Webhook integration.

Webhook Fields Overview

Option	Description
Integration	The selected integration type determines the available fields, which vary based on the chosen integration.
Name*	Descriptive name of the integration.
URL*	Represents the web address where Webhook data is sent when specific events occur, facilitating communication between systems or applications.
Retry Interval	Time duration between consecutive retry attempts that the system makes when there are difficulties in delivering Webhook payloads to the designated endpoint, influencing the timing of retry operations to optimize delivery reliability. Expressed in seconds.
HTTP Method	HTTP protocol method (e.g., POST, GET, PUT) used for sending Webhook payloads to the specified endpoint, determining the action to be performed when communicating with the remote host. When left empty it defaults to POST method.
HTTP Headers	Additional information or metadata provided within the HTTP request that accompanies Webhook payloads, conveying details about the data being transmitted and facilitating proper communication and processing between sender and recipient system.
Password*	Confidential authentication key or secret used in combination with the Username to verify the sender's identity when making HTTP requests to the Webhook endpoint.
Upload certificate	Digital security credential, often self-signed, that is used to establish a secure and trusted connection between the sender and the recipient of Webhook data, ensuring data integrity and confidentiality during transmission.
Content Sample	Represents a content sample of Webhook data is used to verify the Webhook integration works.

Example with Jira Cloud Webhook for creating issue on a project named TEST. Example base on Jira API v2.

Go to the Authentication tab.
Select OAuth and fill in the parameters.
- Client ID: enter the client ID retrieved from the third party entity that you want to integrate with.
- Client secret: enter the client secret from the third party entity you want to integrate with.
- Token URL: insert the OAuth token URL of the third party you want to integrate with.
- Authorize URL: insert here the OAuth authorize URL of the third party you integrate with.
- Audience: is optional, check if the third party requires it or not.
- Scope: is optional, check if the third party requires it or not.
Upload the third party server certificate when self-signed.
Once done, click on Save.
Once saved, run the Authorize call flow by clicking on AUTHORIZE and follow the directions and grant access to resources.

The Authorize call flow continues in getting the authorization to access resources on the third party entity.

The Authorize call flow depends on the third party but works in a similar way:
1. A new window is opened and the third party ask for accepting granting access to the resources.
2. Upon accept/deny user action, the windows is closed and you are prompted back to the Integration view where you can see the authorization status on the SETTINGS panel.
Once authorized, go to SETTINGS panel and click on VERIFY.

Reference

OAuth 2.0 (3LO) apps: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps
Jira Cloud scope: https://developer.atlassian.com/platform/forge/manifest-reference/scopes-product-jira/
Jira API v2: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-users/#api-rest-api-2-user-get