Webhooks

In order to configure a webhook, the /hooks endpoint can be accessed in various ways

Prerequisites

Webhooks must be enabled, please refer to the documentation on "Events" here: WebTSM Services API

Basics

Creating a New Webhook

POST /hooks

Listing All Webhooks Configured By The Current User

GET /hooks

Getting The Configuration Of a Single Webhook:

GET /hooks/{hook-id}

Modifying an Existing Webhook

PUT /hooks/{hook-id}

 Overwrites the entire configuration. Partial updates are not supported

Deleting an Existing Configuration

DELETE /hooks/{hook-id}

Hooktypes

There are two types of hooks that can be configured

1. hooks that are triggered before the triggering request completes
2. hooks that are triggered after the triggering request has been completed (required if information such as response status code from the triggering request is to be included in the callback)

The type is defined in the "Type" property of the webhooks configuration.

Valid types can be looked up at

GET /hooktypes

Simple Configuration Example

This configuration sends a POST request to https://localhost:20111/foo whenever a time series or its data or attributes are retrieved via a GET request. The body of the POST request to the callback URL will contain the complete path of the request.

{
	"PathPattern": "/repositories/*/timeseries/(*)",
	"Callback": "https://localhost:20111/foo",
	"Methods": [
	  "GET"
	],
	"StatusCodeBlackList": [
	  401
	],
	"StatusCodeWhiteList": [],
	"CallbackMethod": "POST",
	"CallbackContent": "$REQUEST_PATH",
	"CallbackContentMediaType": "application/json",
	"Headers": {},
	"Persist": true,
	"Modified": "2019-03-08T10:57:35.438+01:00",
	"Type": 1
}

As you can see the Persist-property of this webhook is "true". This means that the webhook will continue to exist even after a restart of the service. If it were "false" the webhook would not exist anymore when the service is restarted.

Real World Example

The following shows how webhooks can be used to integrate WebTSM Service functionality with third-party applications, in this case Microsoft Teams.

After configuring the "Incoming Webhook" connector within MS Teams, you will get a callback-url from the application

This can be used in the configuration of a WebTSM Service Webhook (see Property "Callback") :

{
    "PathPattern": "repositories/(*)/attributes/(*)",
    "Callback": "INSERT THE CALLBACK-URL HERE",
    "Methods": [
      "GET"
    ],
    "StatusCodeBlackList": [
      401
    ],
    "StatusCodeWhiteList": [],
    "CallbackMethod": "POST",
    "CallbackContent": "{\"@context\": \"https://schema.org/extensions\",\r\n  \"@type\": \"MessageCard\",\r\n  \"themeColor\": \"0072C6\",\r\n  \"title\": \"Attributes-WebHook\",\r\n  \"text\": \"Someone was looking at the attribute $2 on the repository $1. Click **See Attribute $2** to look at the attribute\",\r\n  \"potentialAction\": [{\"@type\": \"OpenUri\",\r\n      \"name\": \"See Attribute $2\",\r\n      \"targets\": [\r\n        { \"os\": \"default\", \"uri\": \"$REQUEST_URI\" }]}]}",
    "CallbackContentMediaType": "application/json",
    "Headers": {},
    "Persist": true,
    "Modified": "2019-04-04T16:58:04.141+02:00",
    "Type": 1
}

Now, whenever someone requests an attribute from the WebTSM Services instance, a message would show up in the MS Teams Channel. In this case, a request to /repositories/ZAMS/attributes/5 led to the message: