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:

1. An application that can respond to a challenge with a 200 OK
2. A valid HCSS access token that belongs to the correct company, has access to the Business Unit you will be subscribing to, and has the correct scopes.

• 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 request scopes at the time of API credentials creation from HCSS Credentials. In the case of Pre-Construction, we need to make sure we have the precon:read scope.

Step 1: Retrieve the Business Unit information

An individual webhook subscription will be scoped to a given Company and Business Unit. Company and Business Unit access are verified at the time of creating a subscription.

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.

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.

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 in the response.

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