Skip to main content
Webhooks in Rules
Updated over 10 months ago

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

  1. Access to the Arcules Web portal, then go to the Rules section:

  2. Create a new rule by pressing the "+" located at the top-right corner:

  3. 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

Did this answer your question?