Share this page

# Listen for webhooks

This topic describes how to use the webhook tool to help develop your own services for integration with OpenText Software Delivery Management.

In this topic:

## Overview

The alm-octane-webhooks-listener tool helps facilitate your understanding of how OpenText Software Delivery Management webhooks work.

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

Using this tool, you can do the following:

- Test out the triggers for your Trigger Webhook rules.

- See the structure (payload) of the 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

## 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 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 OpenText Software Delivery Management 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, click TEST CONNECTION.

If the connection is successful:

- The message Connection succeeded is displayed in OpenText Software Delivery Management 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.

### 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"
            }
          }
        }
      ]
    }

## See also

- Trigger webhooks for other applications
- Design business rules

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: