The “Asset Webhook plugin” allows you to create devices, events and alerts using new HTTP POST endpoints.


Install the Asset Webhook Plugin

Go to your probe's management page and see the list of available plugins. Find the Asset Webhook Plugin, click the overflow menu (3 dots) and choose "Install".




Get Probe's Token

The token is found on the probe management page in the overflow menu:


Create

The end point to add a device:

http://{probeServer}:5000/AssetWebhook/discovery/?Token={theToken}

An example of the json to send

{

    "ID": "TestThing1",

    "Name": "The test thing",

    "Type": "A thing",

    "Data": {

        "Example": 1,

        "Test": "Hello"

    }

}

The id has to be unique to the device(it cannot be reused between calls to this end point). You can update an existing device by resending a request like this with the same ID as earlier. 

N.B. There is currently no way to discover an asset's ID from the Canopy Manage front end, so try not to loose track of it.

A Data value does not need to be set, it can be left out. Items in the data value are free form. You can set whatever values you like.

The Type refers to the Asset Type in Canopy Manage. You can make one in Canopy Manage > Settings > Asset Types.  Use the Asset Type Key here. 

The type will be created if it does not exist. It will be assigned the default status scheme. If it already exists it will not be recreated.


Events

The end point to add an event to a device:

http://{probeServer}:5000/AssetWebhook/event/?Token={theToken} 

And example JSON to send:

{

    "AssetId": "TestThing1",

    "Id": "TestEvent1",

    "EventName": "Thing Happened",

    "EventMessage": "A thing has happened to your thing",

    "Data": {

        "TypeOfThing": "Special",

        "CauseOfThing": "Unknown"

    },

    "Date": "2020-07-15T23:28:56.782Z",

    "LogLevel": 2

}


The asset id needs to match an existing asset. In this case it matches the id created in the create example above.

The event id needs to be unique, it cannot be reused between calls.


Alerts

The end point to add an alert to a device:

http://{probeServer}:{port}/AssetWebhook/alert/?Token={theToken} 

Example JSON to send:

{

    "AssetId": "TestThing1",

    "AssetWarningConditionKey":"Generic:Test1",

    "Created": "2020-07-15T23:28:56.782Z",

    "Title": "A bad test thing happend",

    "Message": "Due to testing a bad test thing happened",

    "Data":{

        "NumberOfBadThings":1

    },

    "WarningLevel": 1

}


The asset id needs to match an existing asset. In this case it matches the id created in the create example above.

The AssetWarningConditionKey can be shared between calls, please note the same key can only appear once per asset (sending the same key to the same asset will over write an existing alert). This is a plain string. It can be whatever you want, it doesn't have to be particular format. N.B. There is currently no way to discover an alert's AssetWarningConditionKey from the Canopy Manage front end, so try not to loose track of it.


A data value does not need to be set, it can be left out. Items in the data value are free form. You can set whatever values you like. Currently this is not visible on the front end.

To set an alert, set the warning level to one of: 2, 3, 4. To clear an asset alert set the warning level to 1.