Listen for ALM Octane webhooks

ALM Octane provides a tool for learning how the ALM Octane webhook mechanism works. This topic describes how to use this tool to help develop your own services for integration with ALM Octane.

Overview

The alm-octane-webhooks-listener tool helps facilitate your understanding of how ALM Octane webhooks work.

The tool simulates how a server application listens for webhook requests.

Using this tool, you can:

Test out the triggers for your Trigger Webhook rules.
See the structure (payload) of the ALM Octane webhook request as it will look when sent to your server.
See notifications in the alm-octane-webhooks-listener console.
Use it as a basis for developing your own services.

Basic authentication is supported.

Install the listener

This section describes how to install the listener.

To install the listener:

Prerequisites:
- Enable the http protocol for Trigger Webhook rules by setting the WEBHOOK_ALLOW_HTTP configuration parameter. For details, see Configuration parameters.
- Install Node.js version 7.10.1 or later.
Clone or download the repository locally: https://github.com/MicroFocus/alm-octane-webhooks-listener
Start node.js.
In the node.js command window, go to the alm-octane-webhooks-listener directory.
Run: npm install

Run the listener

In the alm-octane-webhooks-listener directory, run:

node app [options]

Option	Description
--port	Port to use. Default: 8080
--rcode	Response status code. Default: 200
-u	Username for basic authentication. Default: none
-p	Password for basic authentication. Default: none
--verbose	Print request headers and body. Default: no
--help	Print help and exit.

Example: node app --port=8090 --verbose -u user@domain -p secret

You can now see notifications in the alm-octane-webhooks-listener console.

Example: Getting the listener's URL

Generally, if your ALM Octane installation is on-premises within the same corporate LAN as the node.js, you can use the IP address from the alm-octane-webhooks-listener console as the URL for your Trigger Webhook rule.

If you are using ALM Octane as SaaS, make sure your alm-octane-webhooks-listener is accessible from the internet. In this case the IP address may be different from those proposed by alm-octane-webhooks-listener. Contact your network admin for the URL.

Command

node app  --verbose

Response

Starting up the alm-octane-webhooks-listener.

Available on:

    http://12.34.56.78:8081    (Ethernet)

    http://87.65.43.21:8081    (internal)

Press Ctrl-C to stop the server

Example: Starting the listener with credentials

node app --port=8090 --verbose -u user@domain -p secret

Update the Trigger Webhook rule to call the listener

In the Trigger Webhook rule, update the rule action with the URL of the listener.

To get the URL of the listener, see Example: Getting the listener's URL.

After entering the URL, you can click TEST CONNECTION.

Upon success:

The message Connection succeeded is displayed in ALM Octane Settings.

A notification similar to the following displays in the alm-octane-webhooks-listener console:

[18-Mar-2019 13:18:06.352] POST /?test=true "Apache-HttpClient/4.5.2 (Java/1.8.0_161)"
Received headers:
 {
  "content-type":    "application/json",
  "content-length":  "0",
  "host":            "12.34.56.78:8081",
  "connection":      "Keep-Alive",
  "user-agent":      "Apache-HttpClient/4.5.2 (Java/1.8.0_161)",
  "accept-encoding": "gzip,deflate"
}
Received empty body.

Trigger the webhook

Each time the webhook is triggered, a notification displays in the alm-octane-webhooks-listener console.

Review the notifications and the payload and use this information to develop the service.