Introduction
A webhook is a mechanism to exchange information between applications when an event occurs. This means the application interested in receiving the information (i.e., the receiver) does not have to constantly query the sending application about whether or not the event happened. The communication happens by having the sender application perform an HTTP request to a URL hosted by the receiver application, the latter can process this request and execute specific actions.
As part of the strategy to provide customers with multiple options to receive information when an event takes place, the Arcules Web Portal includes support for Webhooks in its Rules engine. This article describes how you can configure a webhook for a rule and what information can be received when it is triggered.
Configuration
Access to the Arcules Web portal, then go to the Rules section:
Create a new rule by pressing the "+" located at the top-right corner:
Configure the specific details of the rule. When you reach the Action section, for the Select Action Type option select Call Webhook and fill out the corresponding input fields.
Note: the API key and Secret input fields are optional.
Rule Action Parameters
Name | Description | Requirement |
URL | URL of webhook endpoint. The URL should be HTTPS, currently not enforced but this will be required at a later time. | Mandatory |
API Key | The API key used for authentication/authorization in the receiving webhook service. This will be included in the request as a bearer token in the “Authorization” header. | Optional |
Secret | Optional shared secret for message signature generation/validation. If set then an additional “X-Arcules-Signature” HTTP header will be included in the request. The message signature can be verified in the receiving webhook service, see details below. | Optional |
Communication Details
Webhooks will be sent as POST requests to the configured endpoint. Currently, the only authorization scheme supported is an API key passed as bearer token in the “Authorization” header.
The webhook receiver is expected to reply as fast as possible and must reply with a 2xx response code to indicate successful reception of the event.
Message delivery will be attempted up to 5 times with a 5 second delay between retries in case of time-outs (408: request timeout & 504: gateway timeout).
Note: Redirects are not supported.
Request headers
The following HTTP headers are significant:
Name | Value | Notes |
Authorization | Bearer APIKEY | APIKEY is the key entered when setting up the webhook in the rule configuration. Note: If the key is not included in the Rule Action API Key (optional) input field, you won't see this header. |
Content-Type | application/json; charset=utf-8 | Message content (JSON formatted data). |
X-Arcules-Signature | HMAC SHA256 | Included if a Secret is entered in the webhook setup on the rule. This is a message signature that can be used to verify the origin of the message. |
Signature validation
A message signature is provided in the X-Arcules-Signature header if a Secret for hashing has been provided. Using the same secret in the receiving webhook service it can be verified that the message was sent by the Arcules service.
Message body
The webhooks message includes the following fields:
Attribute | Type | Description |
webhook_id | String | UUID for the webhook message. Useful to detect duplicates in case the message is received more than once |
rule_id | String | UUID for the rule for which the webhook has been configured |
rule_name | String | Name of the rule for which the webhook has been configured |
device_id | String | UUID for the device |
device_name | String | Name of the device |
device_type | String | Identifier of the triggering device |
event_type | String | Type of sensor/value |
region_name | String. Only available for object detection events (e.g., People or Vehicle in Region) | Name specified for the region in which an object was detected. |
event_value | Depends on the device type. | The specific value that is related to the event |
event_time | String | Timestamp of event, format following RFC 3339 |
Examples
The following is a set of examples for the message body:
User Defined Device:
{
"webhook_id": "f8a8097e-ea52-4b3d-8bbe-191332a478ee",
"rule_id": "2f6144fb-83f3-4d65-bcf3-99a83e219559",
"rule_name": "Rule for Notification on User Defined Device",
"device_id": "6c5b58a5-279b-496e-85c9-60b01d1f5666",
"device_name": "earthquake sensor",
"device_type": "userdefineddevice",
"event_type": "sensoralarm",
"event_value": "alarm",
"event_time": "2024-02-20T23:28:31Z"
}
Vehicle in Region
{
"webhook_id": "54b57b48-6a5f-43d4-bf80-88f89c53b8db",
"rule_id": "7815f13a-a60c-457d-93a6-6bd22220d163",
"rule_name": "Video Analytics Test",
"device_id": "9917a303-d405-4afe-8cb8-b7dc59c4151b",
"device_name": "Device 1",
"device_type": "video",
"event_type": "vehicleinregion",
"region_name": "Detection Zone 1"
"event_value": 1,
"event_time": "2024-02-20T21:05:09Z"
}
Blur Detection
{
"webhook_id": "59dcf038-1c35-47d0-9ee6-d57152892342",
"rule_id": "3e2af5d9-66c1-4224-8510-f539423220c6",
"rule_name": "Blur Test 1",
"device_id": "8ced3345-6b06-4f9b-93f4-8f1c7fb8bbe4",
"device_name": "Blur and Rotate",
"device_type": "video",
"event_type": "blurdetection",
"event_value": true,
"event_time": "2024-02-20T23:28:31Z"
}
Events Options
Device type, event type and values include the following combinations (some combinations may not be available and other combinations may occur depending on system configuration):
Device Type | Event Type | Event Value |
Gateway | Health Status | Online/Offline |
Camera Analytics | Sensor Alarm | Alarm/Normal |
| Counter | Integer/Number |
| People Counter | Integer/Number |
Video | Health Status | Online/Offline |
| People in Region | Integer/Number |
| Vehicles in Region | Integer/Number |
| Smoke Detection | Boolean |
| Rotation Detection | Boolean |
| Motion Detection | Boolean |
| Tampering Detection | Boolean |
| Blur Detection | Boolean |
| Crowd Detection | Boolean |
| People Loitering | Boolean |
User Defined Device | Sensor Alarm | Alarm/Normal |
HALO | Health Status | Online/Offline |
| Sensor Alarm | Alarm/Normal |
Input/Output | Health Status | Online/Offline |
| Digital Output | Active/Inactive |
| Digital Input | Active/Inactive |