Share this page

# 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.

In this topic:

## 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:

1. 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.

2. Clone or download the repository locally: https://github.com/MicroFocus/alm-octane-webhooks-listener

3. Start node.js.

4. In the node.js command window, go to the alm-octane-webhooks-listener directory.

5. Run: npm install

Back to top

## 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

Back to top

## 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.

Example: Sample notification after adding a defect

If the Trigger Webhook rule has a Submission mode of New, and the Fields are set to Defect type, Description, Detected in release, and Name, a sample response would be:

    Received empty body.
    [18-Mar-2019 13:28:38.570] POST / "Apache-HttpClient/4.5.2 (Java/1.8.0_161)"
    Received headers:
     {
      "content-type":    "application/json",
      "content-length":  "490",
      "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 body:
     {
      "server_url": "http://my-octane-server.net:8081",
      "event_type": "create",
      "sharedspace_id": 1001,
      "workspace_id": 1002,
      "username": {
        "id": 1001,
        "type": "workspace_user",
        "email": "josephine@TheCompany.com"
      },
      "data": [
        {
          "entity": {
            "type": "defect",
            "name": "My New Defect",
            "description": "<html><body><p>This is my new defect. My listener will find it when added.</p>\n</body></html>",
            "id": "2846",
            "detected_in_release": {
              "type": "release",
              "id": "2001"
            },
            "defect_type": {
              "type": "list_node",
              "id": "list_node.defect_type.Escaped"
            }
          }
        }
      ]
    }

Example: Sample notification after updating a defect

If the Trigger Webhook rule has a Submission mode of Update, and the Fields are set to Defect type, Description, Detected in release, and Name, a sample response would be:

    [18-Mar-2019 13:35:54.892] POST / "Apache-HttpClient/4.5.2 (Java/1.8.0_161)"
    Received headers:
     {
      "content-type":    "application/json",
      "content-length":  "632",
      "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 body:
     {
      "server_url": "http://my-octane-server.net:8081",
      "event_type": "update",
      "sharedspace_id": 1001,
      "workspace_id": 1002,
      "username": {
        "id": 1001,
        "type": "workspace_user",
        "email": "josephine@TheCompany.org"
      },
      "data": [
        {
          "entity": {
            "type": "defect",
            "severity": {
              "type": "list_node",
              "id": "list_node.severity.urgent"
            },
            "name": "My New Defect",
            "id": "2846",
            "defect_type": {
              "type": "list_node",
              "id": "list_node.defect_type.Escaped"
            }
          },
          "changes": {
            "severity": {
              "oldValue": {
                "id": "list_node.severity.medium",
                "type": "list_node"
              },
              "newValue": {
                "id": "list_node.severity.urgent",
                "type": "list_node"
              }
            },
            "last_modified": {
              "oldValue": "2019-03-18T11:28:29Z",
              "newValue": "2019-03-18T11:35:44Z"
            }
          }
        }
      ]
    }

Back to top

See also:

- Trigger webhooks for other applications
- Design business rules

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: