Share this page

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

In this topic:

## 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, such as an item, a comment or attachment is created or updated.

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 OpenText Software Delivery Management server. For details, see Modify site settings.

## Customize Trigger Webhook rules

Admins can customize how the endpoint URL is accessed with configuration parameters.

You can customize:

- Whether outgoing requests are sent 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.

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

## Communicate using WebSockets

If the endpoint URL cannot be accessed by the OpenText Software Delivery Management 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 Software Delivery Management and your endpoint URL: https://github.com/MicroFocus/octane-websockets-client-java.

2. Provide the WebSocket with the ability to log in to OpenText Software Delivery Management 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 Software Delivery Management host>:<OpenText Software Delivery Management port>/messaging/shared_spaces/<shared_space>/webhooks

4. Include ALM-OCTANE-TECH-PREVIEW = yes in the header of the connection request.

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

## About the webhook request payload format

When processing a rule with the Trigger webhook action, an HTTP/S POST request is performed 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.
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.
Delete entity | By default, the Trigger webhook action includes only basic fields, such as ID and type.

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.

For examples of the payload format, see Webhook payload format examples.

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

## See also

- Design business rules
- Access and credentials
- Configuration parameters

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: