Trigger webhooks for other applications

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

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 OpenText Core Software Delivery Platform, such as entity creation, deletion, or update.

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

Customize Trigger Webhook rules

Admins can customize how OpenText Core SDP accesses the endpoint URL with configuration parameters.

You can customize:

  • Whether OpenText Core SDP sends outgoing request over HTTP or HTTPS, with WEBHOOK_ALLOW_HTTP.

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

For details, see Configuration parameters.

Back to top

Set up credentials

You might 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 OpenText Core SDP 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 OpenText Core SDP and your endpoint URL: https://github.com/MicroFocus/octane-websockets-client-java.

  2. Provide the WebSocket with the ability to log in to OpenText Core SDP 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://<OpenText Core SDP host>:<OpenText Core SDP 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, OpenText Core SDP 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 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.

  • 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 the delay is not misinterpreted as a failure and keep retrying.

  • The service must return a valid HTTP/S response so that the response is not misinterpreted as a failure of the webhook itself.

To avoid potential abuse, a protection mechanism is provided 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 webhooks.

Back to top

See also: