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

On-premises: 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 an octane.yml file and restarting the ALM Octane server. For details, see the information about configuring other settings in the ALM Octane Installation Guide.

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,

  • On-premises: 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 Set up credentials.

Back to top

Install an integration bridge (on-premises)

If the endpoint URL cannot be accessed by the ALM Octane server, install an integration bridge. See Set up the Integration Bridge Agent.

Back to top

Understand 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 and this video: 

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.

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

As you work in ALM Octane, webhooks are triggered

After configuring the items and settings described above, your work in ALM Octane triggers the webhook rules you created in ALM Octane Settings.

Back to top

See also: