*Using webhooks in macros
- Tom Polman
Technical Article | TA-20201002-TP-43 VDG Sense | Tutorials | Macros  |  |
What is a Webhook action?
Webhooks are “user-defined HTTP callbacks” and can be used in combination with Sense macro signals to trigger the webhook action. The Webhook macro action allows the user to perform POST, GET, PUT, UPDATE and DELETE requests to specific URLs based on any macro signal. For example, when a license plate match is received, a camera I/O is triggered or simply a button is clicked in a layout.
Creating a Webhook action
To create a webhook macro action, open either the Server Macro or Viewer Macro tab, and create a new macro. You can use any macro signal available in the macro engine. To view a list of available signals, click here.
When creating the macro action rules, select the “Webhook” action. Next, select if the webhook should be a POST, GET, PUT, UPDATE or DELETE request. In the input field, fill in the URL of the Webhook. This web server should support HTTPS and therefore the URL should start with https://.
When you choose the method POST, all macro signals including parameters will be posted to supplied url (see example below). When you choose the method GET, it’s possible to include wildcards in the url based on the macro signal. The following wildcards are available (case-sensitive):
%EventId%
The ID of the event which triggered the macro%EventName%
The name of the event (Connection Lost, Motion e.a.)%EventValue%
The value of the given event%DeviceId%
The unique ID of the device%ServerId%
The unique ID of the server on which the device resides%DeviceName%
The name of the device/camera%ServerName%
The name of the server on which the device resided
Authorization
If required, you can set the basic authorization of the request. Click the button “Authenticate”, which will open the following dialog:
Click the “Skip certificate verification” for use with self-signed SSL/TLS certificates.
Webserver implementation
The webhook is successfully executed when the webserver returns a 200 status code.
The request will timeout after 3 seconds and will be handle as a failure.
When the request fails, it will retry the request two more times with a delay of 5 seconds (max 3 attempts).
When the macro action has failed more than 10 times, the macro will be deactivated.
All failures will be written to the logs.
Use Case examples
In these examples we expect you to know how you setup a web server with HTTPS that runs PHP and/or NodeJS. Create a macro action of the type POST and enter the url of the php page. Once the macro action is executed, it will post the following JSON data to the supplied url.
{
"macro": "Web hook",
"signals": [
{
"DeviceId": "1",
"DeviceName": "Device 1",
"EventId": "2807",
"EventName": "GenericEvent",
"EventValue": "Hallo!",
"GenericEvent": "Hallo!",
"ServerId": "2305731320131193796",
"ServerName": "Desktop-qfovcoo",
"signalrecordid": "2807",
"signaltimestamp": "2019-07-23 11:48:46.520"
}
]
} |
Below an example in PHP how you could write the post body to a text file. This is purely for demonstration, you would probably write some extra logic to do something with the posted data.
ob_flush();
ob_start();
$postdata = file_get_contents("php://input");
$jsondata = json_decode($postdata);
var_dump($jsondata);
file_put_contents("log.txt", ob_get_flush()); |
The log.txt will be
object(stdClass)#1 (2) {
["macro"]=>
string(8) "Web hook"
["signals"]=>
array(1) {
[0]=>
object(stdClass)#2 (10) {
["DeviceId"]=>
string(1) "1"
["DeviceName"]=>
string(8) "Device 1"
["EventId"]=>
string(4) "2807"
["EventName"]=>
string(12) "GenericEvent"
["EventValue"]=>
string(6) "Hallo!"
["GenericEvent"]=>
string(6) "Hallo!"
["ServerId"]=>
string(19) "2305731320131193796"
["ServerName"]=>
string(15) "Desktop-qfovcoo"
["signalrecordid"]=>
string(4) "2807"
["signaltimestamp"]=>
string(23) "2019-07-23 11:48:46.520"
}
}
} |
Below an example in NodeJS how you could write the post body to a text file.