SKOOR Documentation

Webhook

Function	Webhook jobs are used to receive data from outside the SKOOR Engine, using its REST API. The job will wait for input values (numerical and string values) and store the value history of incoming values.
Alarming	Error code, Values, String values

For this type of job, the collector must be set to one that can be used to authenticate the REST calls. If not done yet, create a user of type Collector in /root/Users/Users.

Webhook detail

Webhook parameters

Parameter	Description
Timeout after	If set, the job's error code will be set to 5 (Timeout Error) if no data is sent to the job during the specified time. The timeout must be reset by the error code sent with the next data delivery
Values	Add a value for each numerical value that will be sent to the SKOOR REST API. For each value a Unit definition button allows specifying the value's name, unit, divisor, precision and description
String values	Add a string value for each string value that will be sent to the SKOOR REST API. For each string value a Unit definition button allows specifying the string value's name, unit and description

Webhook values and alarm limits

Value / Alarm limit	Description
Value 1-x	User defined numerical value
String value 1-x	User defined string value
Error code	Generic job error code (see section Job error codes)

Feeding data to a Webhook job

Any REST client can be used to send values and string values to the Webhook job. In this example the curl command line tool is used. The following lists a simple bash shell script that will feed the job with 2 numerical values and 1 string value each time it is run.

An error code must be sent together with the values to reset error code 5 (Timeout error) if Timeout after is set in the job configuration

#!/bin/bash
  
HOST="10.1.0.89"
USER="webhook"
PASSWORD="webhook"
JOBID=830

SESSIONID=$(curl -s -k "https://${HOST}/skoor-webservice/session/login?username=${USER}&password=${PASSWORD}" | python -m json.tool | grep sessionId | cut -d"\"" -f4)

curl -s -k -X POST -H "Content-Type: application/json" -d '{"returnValue1":24.42,"returnValue2":99,"stringValue1":"Skoor Test 3","errorCode":0}' "https://${HOST}/skoor-webservice/webcollector/jobs/$JOBID/values?sessionId=${SESSIONID}"

curl -s -k "https://${HOST}/skoor-webservice/session/logout?sessionId=${SESSIONID}"

The script first defines some variables:

HOST: The IP address or hostname of the SKOOR Server where the Webhook job is configured
USER: The name of the collector user configured on the SKOOR Server
PASSWORD: The collector user's password
JOBID: The ID of the Webhook job that should receive the values

Then a login is performed to the SKOOR Webservice, receiving a session ID. The session ID is a string that looks like this: d6c38ad55e80b4a3bed39d55699b824e.

The curl command sends the values using the returnValueX and stringValueX notation within a POST request to the SKOOR Webservice, together with a valid session ID.

The body of the POST request looks like this:

{
    "returnValue1": 24.42,
    "returnValue2": 99,
    "stringValue1": "Skoor Test 3",
    "errorCode": 0
}

{
    "returnValue": [24.42, 99],
    "stringValue1": "Skoor Test 3",
    "errorCode": 0
}

The data to be fed can be from any source, as long as it can be passed to the REST client.

Always send the POST request using the appropriate header Content-Type: application/json.

As a final step the script logs out of the session. Make sure to implement a logout otherwise running this script regularly will leave many sessions open on the SKOOR Server.

The script can reside and be run from any host that can reach the SKOOR Engine server via its HTTPS Port TCP 443.

For further information on the REST API, please find the webservice guide available on every SKOOR Engine installation on https://<SKOOR server>/skoor-webservice.

Before running the script, the 2 values and 1 string value need to be defined on the Webhook job using their corresponding Unit buttons:

Once the script is run, the Webhook job should have received the values:

The Value 1 puts the job into state Minor since the following alarm limits have been defined on the job: