OSS Webhook User Guide

Introduction

This document provides instructions on how to install and use the OSS Webhook server module.
This module enables external services to send data to a Niagara station using a Webhook.

Requirements

It is assumed that the user is trained in the use of Niagara 4.
The OSS Webhook software is only compatible with Niagara versions 4.10 or later.

Installation

Software Module Installation

Before the OSS Webhook software can be used,the Niagara software modules must be installed on the user’s PC and the target host.
The ‘ossWebhook-rt.jar’ and ‘ossWebhook-wb.jar’ filessupplied by One Sight Solutions must be installed on the host using the Niagara platform software manager.
This software file must also be installed in the appropriate Niagara modules directory of any PC on which you intend to access the OSS Webhook software.

Software Licensing

The host running the OSS Webhook software must be licensed by One Sight Solutions before it will operate correctly.
The following information is required to generate the OSS Webhook license:

– Niagara host identifier (e.g. Qnx-TITAN-0000-XXXX-XXXX).

– Niagara host serial number(if the host is not a supervisor).

Please send this information to One Sight Solutions: sales@onesight.solutions
It is recommended that the license is installed on the Niagara host using the platform license manager import capability to download the license directly from the Niagara license server over the internet.
If it is not possible for the host to download the license from the internet then One Sight Solutions can supply the necessary license files which can be installed manually.
Ensure that the One Sight Solutions certificate is also installed, so the Niagara platform license manager should show both of the following files:

– OneSightSolutions.license

– OneSightSolutions.certificate

The host should reboot during the license installation process.

Getting Started

The following is a basic introduction to using the OSS Webhook software.
First open the ‘OSS Webhook’ palette.
Drag the OssWebhookService component from the palette into the Niagara Services folder.
Expand the installed OssWebhookService componentso the ‘Endpoints’sub-folder is visible.
Drag an ‘Endpoint’ component from the palette into the ‘Endpoint’ folder.
Name the new endpoint component the identifier you wish to use for the webhook endpoint URL.
This should look something like below:

This now makes an unauthenticated HTTP webhook endpoint available that external systems can post data to.
To test the endpoint you have to send a HTTP POST request to the Niagara web server with the URL path starting with ‘ossWebhook’ followed by the name you gave your endpoint.
For example, if you called the endpoint ‘tempSetpoint’ and were accessing it from the same machine then the URL would be:
http://localhost/ossWebhook/tempSetpoint
Note that by default Niagara is configured to disable all insecure HTTP requests, so for this test to work you would need to enable insecure access in the Niagara Web Service by enabling HTTP (‘Http Enabled’ to true) and disabling HTTPS only (‘Https only’ to false). This is shown below.

As these settings put the Naiagara station in an insecure state, make sure you change these settings back to the secure defaults when you have finished testing.
One simple way to test this insecure webhook is to use the Microsoft Windows built-in ‘curl’ PowerShell command.
Open a PowerShell prompt and enter the following command:

curl -URI "http://localhost/ossWebhook/tempSetpoint" -Method "POST" -Body "21.5"

This will send the value ’21.5’ to the endpoint ‘Out’ property.

The PowerShell output should look like this:

OSS Webhook Palette

This is the OSS Webhook Palette

This table has a brief description of each item in the palette.

Component	Function
OssWebhookService	The OssWebhook software service.
Endpoint	The component used to represent a Webhook endpoint.
AuthBasic	A basic authentication definition.
AuthApiKey	An API key authentication definition.
AuthBearerToken	A Bearer Token authentication definition.
AuthHmac	A HMAC authentication definition.
AuthGroup	A group of authentication definitions.

OSS Webhook Component Reference

OssWebhookService

The OssWebhookService is the container for all elements that define the webhook endpoints and authentication credentials.

Authentication Folder

The ‘Authentication’ folder contains all the authentication credential definitions that can be used by the webhook endpoints.
Note that each authentication definition can be used by more than one endpoint.
Authentication definitions can be added to the folder by dragging from the palette or using the folder actions.

These authentication credential components are described further in the following sections.

Endpoints Folder

The ‘Endpoints’ folder contains all the endpoints definitions.
A new endpoint definition can be dragged from the palette or added using the folder action.

Endpoint

The ‘Endpoint’ component is used to define an endpoint available from the webhook service when placed in the service endpoint folder.
A new endpoint definition can be dragged from the palette or added using the folder action.

Endpoint URL

The name of the endpoint component is used as the suffix to the endpoint URL.
All OSS Webhook endpoint URLs start with the ‘ossWebook’ prefix (after the host name).
The name of the endpoint component is placed after this prefix (separated by a forward slash).
For example, if an endpoint component is named ‘meterData’ then the OSS Webhook endpoint URL would be:

https://<host-name>/ossWebhook/meterData

Endpoint Properties

Enable

If the ‘Enable’ property is set to false then any requests to this endpoint will return an error (400,
bad request). Otherwise the endpoint will operate normally.

Auth Selection

The ‘Auth Selection’ property defines the authentication to be used for the endpoint.
A drop down list of options is provided.
When the default ‘No Auth’ option is selected no authentication is required to access the endpoint.
All other options are obtained from the list of authentication credential definitions that have been added to the service ‘Authentication’ folder.

Post Data

The ‘Post Data’ property contains the data that has been sent to the endpoint in a POST request.
This data can be cleared by using the ‘ClearPost Data’ endpoint action.

Post Content Type

The ‘Post Content Type’ property contains the HTTP header ‘Content-Type’ MIME type that was sent with the endpoint POST request. This usually describes the post data format.

Last Request Time

The ‘Last Request Time’ contains the time of the last request to this endpoint.

Authentication Definitions

Authentication definitions are taken from the authentication options section of the OSS Webhook palette and placed in the service Authentication folder.
Various types of authentication credentials are available as described in the following sections.
Each endpoint can select a single authentication definition or a ‘AuthGroup’ component can be used to allow an endpoint to support multiple different authentication definitions.
Each authentication definition can be used my more than one endpoint.
All authentication definitions have an expiry mechanism.
All authentication definitions also have an enable property which when disabled makes the authentication entry invalid.
It should be noted that these authentication mechanisms do not provide any encryption capability. If data encryption is required then the application should enforce HTTPS connections to provide this.

AuthBasic

The AuthBasic component provides HTTP basic access authentication (RFC 7617).
This allows simple user, password information to be stored in HTTP header of the webbook endpoint request.

AuthApiKey

The AuthApiKey component provides an API key authentication capability.
The API key may be provided in an endpoint client request either as a HTTP header or as a URL query.
The component has properties to control whether a header entry, URL query or both are allowed.
The ‘Key Name’ property defines a name that is either used as the HTTP header name or the URL query parameter key.
The ‘Key Value’ property defines the value that the endpoint client must set the key value to.
For example, if the Key Name is set to ‘XToken’ and the Key Value is set to ‘123456’ then a client can be authorised by including the following HTTP header:

XToken: 123456

Or by adding the following URL query to the end of the endpoint URL:

?XToken=123456

AuthBearerToken

The AuthBearerToken component provides support for an OAuth 2.0 compatible bearer token HTTP header(RFC 6750).
The ‘Token Value’ property is used to specify the bearer token value.
This token value must then be included in the endpoint request HTTP header in the usual format by adding a ‘Authorization’ HTTP header entry with the value ‘Bearer’ followed by a space and then the required token value:

Authorization: Bearer <Token-Value>

AuthHmac

The AuthHmac component provides support for using a HMAC cryptographic hash function to validate the integrity of the data posted to the endpoint using a secret key.
The ‘Header Name’ property defines the HTTP header name that will be used to store the generated hash value.
The ‘Hash Algorithm’ property defines the hash algorithm that is used to generate the hash value from the secret key and the post data.
The ‘Secret Key’ property defines the secret value that will be combined with the post data to generate the hash value.
This authenticationmechanism has the advantage that the contents of the data posted to the endpoint can be verified as well as providing an authentication capability. But this does require additional work by the client to generate the hash value for every request.

AuthGroup

The AuthGroup component allows an endpoint to support more than one authentication definition.
Authentication definitions are placed inside the AuthGroup component and then if an endpoint choses the AuthGroup for it’s Auth Selection then any of the nested authentication definitions will be valid for that endpoint.

Authentication Definition Expiry

All authentication definitions have expiry properties.
If the ‘Enable Expiry’ property is set to false then the definition will never expire.
Otherwise the definition will remain valid until after the date/time defined by the ‘Expiry’ property.

Examples

URL API Key Authentication

This example shows the use of an endpoint with URL API key authentication.
This mechanism places the user defined API key at the end of the endpoint URL.
The OssWebhookService properties are shown in the following screenshot:

The PowerShell curl command for sending data to this endpoint would look like following:

curl -URI "http://localhost/ossWebhook/loraData?token=zPShY8Uh0LidgL2j"
-Method "POST"
-Body "{'devEUI':'12345678abcdefgh','temperature':20.7}"

HTTP Header API Key Authentication

This example shows the of use an endpoint with HTTP header API key authentication.
This mechanism places the user defined API key in the HTTP header.
The OssWebhookService properties are shown in the following screenshot: