How to use HCSS Webhooks

Webhooks allow an application to receive notifications when an event occurs, rather than having to consistently poll an API to check whether or not there were changes to any data you may find relevant.

As an example, when a HeavyBid Pre-Construction project changes, HCSS will make a POST request to a callback URL you configured to let you know about the changes to the project.

You can configure what events you would like to listen for when setting up your webhook.

Prerequisites

In order to start using webhooks, you need the following in addition to a product which supports webhooks:

1. An application that can respond to the subscription challenge GET request with a 200 OK
2. An HCSS API Client configured with the correct scopes needed for creating the subscription request. In the case of Pre-Construction, we need to make sure we have the precon:read scope, For Setups it should be dis:read, and for HeavyJob it should be heavyjob:read
3. A valid HCSS access token generated with these client credentials that has access to the Business Unit and Company you will be subscribing to.

• Company access - In most cases, when you request a token it will be automatically created to belong to your company. This is not the case if you are an HCSS partner. You can read more about HCSS partner workflows here.
• Business Unit access - In Step 1, you will be retrieving Business Unit information. Your token must have access to the Business Unit you are trying to create a subscription to. If you have generated your token using generated API credentials from HCSS Credentials, you should have access to create a Webhook for any Business Unit in your company.
• Scopes - Each HCSS product will have their own scopes required to create subscriptions. You can modify client scopes inside of HCSS Credentials.

Enhanced Security (Optional)

Securing webhooks involves validating the webhook payload and webhook sender by using signature verification. Using this enhanced security workflow allows your application to validate payloads and filter out anonymous POST requests sent to your Callback URL.

Utilizing our enhanced security measures is optional. Webhooks are fully functional after successfully subscribing to a webhook event.

The Security Process:

1. When you create a Webhook you may pass a "SecretKey" parameter in the request body. If you leave this out of your request, it will be randomly generated by HCSS. This secret key is known by both the webhook producer and consumer, it will be used by your application to validate a webhook POST request.
2. HCSS webhook POST requests have unique signatures made by processing your SecretKey with an HMAC hashing algorithm (SHA-256 in our case) to create a cryptographic hash of the webhook payload. This hash is the signature.
3. This dynamic signature is added to all webhook POST requests made by HCSS inside of a custom "X-HCSS-Signature" header. You may have your application callback url reject webhooks missing this header.
4. When a webhook POST request arrives at your callback URL, your application may calculate its own signature using the webhook payload, "SecretKey" and cryptographic algorithm (SHA-256).
5. Your dynamically calculated signature can then compared with the one sent by the producer in the "X-HCSS-Signature" header. If there is a signature match then the request is valid, and you may trust and utlize the paylod. If there is no signature match, you may have your application reject this request and its payload.

Step 1: Retrieve the Business Unit information

An individual webhook subscription will be scoped to a given Company and Business Unit.

Company information is automatically generated for you when you create an access token.

To get a list of Business Units, make a GET request to the Business Unit endpoint.

Step 2: Create a Webhook Subscription

In order to setup your webhook, you must configure a subscription so that HCSS knows where your application lives that will receive events. Make a POST request that specifies the URL of your application, also known as a callback URL, and the event types that you would like to receive updates for.

Your application must be able to respond to the challenege submitted to your application by this request or your will not receive webhook updates!

Challenge Verification

The first time you create a subscription, HCSS will check that your given callback URL is valid via a GET request to your endpoint that includes a challenge query parameter. Your application must return the exact value of the challenge query parameter in the body of the response and a HTTP 200 Status code. Be sure to return only the challenge field in the challenge response body.

Make a POST request to the subscription endpoint.

NOTE: If your organization uses a URL from Azure websites, it may require some manual steps on the HCSS side. Please contact us if that is the case, and our team will be happy to help.

Step 3: Receive events

Once you have your webhooks created, HCSS will send updates to your application, and your application must respond with a HTTP 200 Status code in order to avoid having your subscription stopped.

Stopped Webhooks

When trying to POST updates to your app, HCSS will try 5 times to reach your app with updates, with exponential wait time growth. If HCSS receives any code other than a HTTP 2xx Status code from your application, then your subscription will be marked as stopped after these 5 tries.

In order to mark your subscription as active once again, you must go back to Step 2.

You can query your list of Active and Stopped subscriptions by making a GET request to the webhooks endpoint.

Step 4: Deleting Webhooks

If you have an application that you would like to stop receiving updates to, you can make a DELETE request to the delete endpoint. Each product has its own get, subscribe, update, and deletion endpoint.