Webhooks integration package

Webhooks serve as a communication mechanism between systems. A webhook subscribes to HCL Compass and waits. When events are triggered, HCL Compass sends information out to the subscriber.

The Webhooks integration package installs into HCL Compass like any other integration package. The webhooks integration package allows you to:

Create a webhook configuration (WebhookConfig) for a server that wants to be notified of events that occur in HCL Compass.
This configuration allows the user to select states and/or actions that the server should be notified of.
The user or other users use HCL Compass as they need. For example, creating, assigning, resolving, duplicating, postponing defects.
Anytime an action or state change occure that matches with what was selected in the configuration, a payload (WebhookData) is created by HCL Compass.
Periodically, HCL Compass checks for webhooks, and delivers any pending WebhookData objects to the subscriber or subscribers.

By default, webhooks configurations are refreshed every 15 minutes. WebhookData objects are polled every minute and are deleted upon successful delivery. If the remote system does not catch the webhook, HCL Compass automatically retries to deliver the payload up to 10 times.

Installing the Webhooks package

Install the Webhooks package by completing the following steps:

Open the Compass Designer.
Log in to the desired repository.
Right-click the reposority in the left sidebar and click Install Package.
In the Install Package Wizard, expand the Webhooks package and choose version 1.0 of the package.
After the installation completes, click Finish, then OK.
In the left sidebar, expand to the desired repository and expand the schema that you want to apply the package to.
Right-click the currently loaded version of the schema, and navigate into Packages, then click Apply Packages.
Expand the Webhooks packages and choose version 1.0 of the package, then click Next.
Checkmark the record types to apply the Webhooks package to. These are the record types that you will be able to configure webhooks for. For example, you will be able to configure a webhook that will receive payloads from Compass whenever a record of one of the checkmarked types is created.
Check in the new version of the schema by right-clicking the version in the left sidebar and navigating to Revision Control, and then Checkin.
Upgrade the desired database with the new schema version by clicking the repository in the left sidebar where the package was installed and applied. Navigate to the Compass Database Admin tab at the bottom center of the Compass Designer.
Right-click the database to upgrade with the new schema version and click Upgrade Database. Click the desired schema version and click OK.

Configuring the webhooks package for use in Compass

Using an administrator account, create a record of type Webhook_Master. Provide any groups that should be allowed to create and manage webhooks (WebhookConfig records) and a callback URL to the Compass REST API server. It is recommended, but not required, to create a group specifically for users with access to manage WebhookConfig records.
Create a WebhookConfig record. You may need to log out of Compass and log back in for this option to appear. Provide a webhook name and URL, and optionally, a secret for securing the webhook and description. The secret will be used to hash the payload that is delivered to webhooks so that the receiver can verify the payloads validity.
Also, choose a Tracked Record, which will be the record type that you want to receive payloads about. The default Webhook Type is set to Commit, which means that payloads will only be sent when actions executed on records of the tracked type are successful. If you want payloads to be sent regardless of success, choose Notification.

In the Controls tab, choose a combination of Actions and/or States that you wish for your webhook to receive payloads about. For example, choosing the Submit action triggers a payload to be sent any time the Submit action is used on a record type.
Using any API client, such as Postman or the command line, create an HTTP POST request to the REST API servers hookSetup endpoint. This enables the server for use with the Webhooks package by creating a system user that can execute the necessary actions in Compass. The credentials that you provide in the payload should belong to a user that has permission to create users. API calls to the hookSetup endpoint can only be executed by a user with User Maintenance privileges or higher.
Example URL: https://localhost:8190/ccmweb/rest/hookSetup
Example payload:
```
{
	"username": "admin",
	"password": "",
	"repo": "TestRepo",
	"db": "SAMPL"
}
```
Restart the Compass REST API server for these changes to take effect.

Usage

After the initial setup is complete, using the Webhooks package is simple.

Any time that one of the following occurs, a payload containing information about the relevant record will be delivered to the registered webhook:

Any of the actions chosen in the WebhookConfig record are triggered on the chosen Tracked Record.
The Tracked Record is moved to any of the states chosen in the WebhookConfig record.

The Compass REST API server will attempt to deliver the payload 10 times before giving up and removing the payload from its queue. The webhook must respond to the incoming payload with a successful or unsuccessful HTTP status code and a response body containing a message in order to continue proper execution of payload deliveries to the webhook.