Trigger webhooks for other applications

ALM Octane supports webhooks for integrating with other applications. Configure the webhooks by creating a rule with the Trigger Webhook action. This topic provides end-to-end instructions for setting up webhooks.

Overview

The webhook mechanism supports advanced workflow use case scenarios and enables integration with other applications.

Trigger webhook rules send an HTTP/S request, with a payload in JSON format, to an endpoint URL when an event occurs in ALM Octane, such as entity creation, deletion, or update.

At the endpoint URL, an application receives the requests and processes the information.

Configure proxies

You may have to ask the site admin to configure your organization's proxy so that outgoing requests are not blocked.

Proxies are set by modifying the proxy.conf file and restarting the ALM Octane server. For details, see Modify site settings.

Back to top

Customize Trigger Webhook rules

Admins can customize how ALM Octane accesses the endpoint URL with configuration parameters.

You can customize:

  • Whether ALM Octane sends outgoing request over HTTP or HTTPS, with WEBHOOK_ALLOW_HTTP.

    When using HTTP, use only the standard port 80 for outgoing requests,

  • At what point the HTTP/S request times out, with WEBHOOK_REQUEST_TIMEOUT.

For details, see Configuration parameters.

Back to top

Set up credentials

You may have to ask an admin to define credentials to be used for authenticating the request.

Trigger webhook rules support basic authentication. When you set credentials in the Trigger webhook rule, each webhook request includes a basic authentication header.

For details, see Credentials.

Back to top

On premises: Communicate using WebSockets

If the endpoint URL cannot be accessed by the ALM Octane server, set up a WebSocket to enable this communication.

WebSockets enable a server and client to send messages to each other at any time, after a connection is established, without an explicit request.

To communicate using WebSockets:

  1. Using a WebSocket client, create a WebSocket which opens a tunnel between ALM Octane and your endpoint URL. For details, see https://websockets.readthedocs.io/en/stable/index.html.

  2. Provide the WebSocket with the ability to log in to ALM Octane using API access keys:

    1. Generate an API key with CI/CD Integration role. For details see API access.

    2. Assign this API key to the workspaces that will use the WebSocket connection.

    We recommend using a dedicated API key for this purpose.

  3. Enter the following details in the WebSocket configuration:

    ws://<ALM Octane host>:<ALM Octane port>/messaging/shared_spaces/<shared_space>/webhooks

  4. When creating the Trigger webhook rule action, select the WebSocket communication method.

Your WebSocket listens to changes in the workspaces with CI/CD Integration role in the specified shared space, and triggers the webhook action that you created.

Back to top

About the webhook request payload format

When processing a rule with the Trigger webhook action, ALM Octane performs an HTTP/S POST request to the endpoint URL. The POST includes a JSON request payload.

Tip: Use the alm-octane-webhooks-listener tool to simulate the web service and to see the structure of the request payload. For details, see Listen for ALM Octane webhooks.

Different payloads are sent depending on which event triggered the webhook.

Event Request payload
Create entity By default, the Trigger webhook action includes only basic fields, such as ID and type.
Delete entity By default, the Trigger webhook action includes only basic fields, such as ID and type.
Update entity By default, in addition to the basic fields, such as ID and type, the Trigger webhook action includes a set of "before/after" changes.

When creating the Trigger webhook rule, you can select additional fields to include in the request payload by specifying Fields.

UDFs are supported in Fields.

Payload format example

Parts of the payload

The payload for an update event consists of the following parts: 

Part Description
Header information

Sent with every Trigger webhook rule, and consists of:

  • server_url
  • event_type
  • username
  • sharedspace_id
  • workspace_id
Basic information

Fields that are sent with every Trigger webhook rule. These fields include: 

  • id: ID of the entity.
  • type: Type of entity.

  • (Version 24.3 and later) audit_id: Activity log ID of the triggering event, if the event was recorded in the activity log. For details, see View the activity log.

    Note: If an event exceeds the maximum length allowed for an activity log entry, the event is split and logged as multiple entries in the activity log. The webhook payload contains the entire record of the event, and the payload's audit_id value matches the ID of the first activity log entry of the event. The other event entries can be associated with the event using the property aggregated_event_id, which has the same value across all of the event's entries.
Additional information Additional fields that you can add to the request payload, using Fields when setting up the Trigger webhook rule.
Changes

If the event_type is update, the changes field is included in the request payload.

The changes field includes the set of changes, including the values before and after the update.
Field type Sample snippets
Primitive

Basic system fields, such as id, type, last_modified. 

"changes": {
  "last_modified": {
    "oldValue": "2017-12-26T15:51:22Z",
    "newValue": "2017-12-26T15:49:22Z"
  }
}
User

User information. 

"detected_by": {
  "id": 1991,
  "type": "workspace_user",
  "email": "MyEmail@MyCompany.com"
}

"changes": {
  "detected_by": {
    "oldValue": null,
    "newValue": {
      "id": 1002,
      "type": "workspace_user",
      "email": "YourEmail@YourCompany.com"
    }
  }
}
List node

Object of type and ID, such as phases.

"phase": {
  "type": "phase",
  "id": "phase.defect.new"
}

"changes": {
  "phase": {
    "oldValue": {
      "type": "phase",
      "id": "phase.test_manual.new"
    },
    "newValue": {
      "type": "phase",
      "id": "phase.test_manual.planned"
    }
  }
}
Multi-list nodes

Total count in addition to the array of list nodes, such as the list of test types.

"test_type": {
  "total_count": 2,
  "data": [
    {
      "type": "list_node",
      "id": "list_node.test_type.performance"
    },
    {
      "type": "list_node",
      "id": "list_node.test_type.regression"
    }
  ]
}

"changes": {
  "test_type": {
    "oldValue": [
      {
        "type": "list_node",
        "id": "list_node.test_type.performance"
      },
      {
        "type": "list_node",
        "id": "list_node.test_type.regression"
      }
    ],
    "newValue": [
      {
        "type": "list_node",
        "id": "list_node.test_type.performance"
      }
    ]
  }
}
Reference

Object of type and id, such as release. 

"release": {
  "type": "release",
  "id": "2002"
}
Multi-reference

Total count in addition to the array of reference entities, such as application modules (previously known as product areas). 

"application_modules": {
  "total_count": 2,
  "data": [
    {
      "type": "application_module",
      "id": "2002"
    },
    {
      "type": "application_module",
      "id": "2001"
    }
  ]
}

"changes": {
 "application_modules": {
    "oldValue": [
      {
        "id": 1001,
        "type": "application_module"
      }
    ],
    "newValue": [
      {
        "id": 1002
        "type": "application_module",
      }
    ]
  }
}

Back to top

Set up a web service at the endpoint

Set up and run a service at the endpoint that receives the requests and processes the information.

We recommend that you use an HTTP client tool like Postman or Telerik Fiddler for developing and testing the web service.

When setting up the web service, follow these guidelines to ensure that the webhooks are triggered:

  • The service sends an HTTP/S response quickly so that ALM Octane does not misinterpret the delay as a failure and keep retrying.

  • The service must return a valid HTTP/S response so that ALM Octane does not misinterpret the response as a failure of the webhook itself.

To avoid potential abuse, ALM Octane provides a protection mechanism that blocks URLs if the above guidelines are not followed.

Tip: Use the alm-octane-webhooks-listener tool to simulate the web service. For details, see Listen for ALM Octane webhooks.

Back to top

See also: