Creating a webhook

This topic describes how to use HCL Compass to create a new webhook.

1. Create a WebhookMaster configuration by using the New... menu.
   The WebhookMaster configuration is the container that holds all of your webhook configurations. You can choose a group to manage who can created webhook configurations. Only 1 WebhookMaster configuration can be created.
2. Fill in the details for the WebhookMaster configuration as propmpted by the User Interface.
   Click the Add button to select a group in the pop-up window. The group that you choose allows all of the users in that group to create webhooks. The pop-up window may not populate a list of available groups until you click the Search button.
3. Create a new WebhookConfig by using the New... menu.
   If the menu does not update properly, you may need to lot out and log back into HCL Compass.
4. Fill in the details for the webhook configuration.
   • This is the form where you specify the server that should listen for events from HCL Compass (URL), and which events to listen for (set your events on the Controls tab). This server should be capable of providing responses with an appropriate status code and body after receiving an event, whether successfully or unsuccessfully.

     For example, a server that successfully receives a webhook payload should respond with the following:

     Status code: 200
     Response body (JSON):
     {
        "message": "Payload received successfully"
     }

     A server that unsuccessfully receives a webhook payload should respond with the following:

     Status code: 500 (or any other HTTP status code signifying an error)
     Response body (JSON):
     {
         "message": "Payload received unsuccessfully"
     }

     These status codes and error messages can be viewed during the lifetime of a specific payload. Configuring your server to return helpful status codes and messages is important for webhooks to function properly and to troubleshoot why a webhook may not be working properly. For more information, see Managing and debugging webhooks.

   • The Secret is used to secure the webhook.

     The secret is provided by the user and is used by the REST API server to hash the payload by using the HMAC-SHA1 hash function. It is hashed and sent by HCL Compass as part of the X-Ccm-Signature in the headers of the HTTP request when the webhook payload is delivered to the listening server.

     To validate the HTTP request containing the payload, you can take the webhook secret that you created and the payload that you received from HCL Compass and provide them to the same hash function. After hashing, they should match what is in the X-Ccm-Signature header. If they are the same, you have validated that the HTTP request and the webhook payload it contains came from HCL Compass.

   • Tracked Record is the record type that you want to use the webhook with.
   • Webhook Type can be either Commit or Notification. The Commit type is for successful actions. The Notification type will create and deliver a payload regardless of whether or not a tracked action is successful.
5. Use the Controls tab to choose the state and/or actions for the webhooks to receive information about.
   If you click one of the pencils to choose the desired state or action to track, a pop up will load endlessly. Exiting the pop up displays an exception. This is a known defect. To workaround the issue:

   1. Exit the two pop ups.
   2. Save the current state of the webhook configuration, but don't close the form.
   3. Click Modify.
   4. Clicking the pencils in the Controls tab should now show pop-ups that are properly populated.
   5. After making your selection, click Submit and then click Add to add it to the webhook.
   6. You can now save and close your webhook again.
6. Click Save and Close to save the webhook.