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 Software Delivery Platform accesses the endpoint URL with configuration parameters.

You can customize:

  • Whether OpenText Core Software Delivery Platform 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 Software Delivery Platform 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 Software Delivery Platform 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 Software Delivery Platform 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 Software Delivery Platform host>:<OpenText Core Software Delivery Platform 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 Software Delivery Platform 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 OpenText Core Software Delivery Platform 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

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 OpenText Core Software Delivery Platform does not misinterpret the delay as a failure and keep retrying.

  • The service must return a valid HTTP/S response so that OpenText Core Software Delivery Platform does not misinterpret the response as a failure of the webhook itself.

To avoid potential abuse, OpenText Core Software Delivery Platform 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 OpenText Core Software Delivery Platform webhooks.

Back to top

See also: