Hook System

The friendly integration method, also known as hook system, enables seamless communication between our application and external systems. This feature allows us to send notifications or requests to external systems in real-time, without requiring manual intervention.

How it Works

Trigger: A specific event occurs within our application, such as the creation of a new task.
Request Sent: The webhook is triggered and sends an HTTP request to your external system with relevant data.
Response Received: Your external system processes the request and sends back a response to the hook system.

Benefits

The hook system offers several benefits, including:

Real-time notifications: Receive instant notifications when events occur within our application.
Automated workflows: Integrate with external systems to automate workflows and improve efficiency.
Improved user experience: Enhance user experience by providing seamless integration with external services.

Supported Event Type

Event Type	desc (emit when ...)
infer.rule	new infer data from rule service
infer.link	new infer data like ooline/offline status
alert.trigger	an alert is triggered
new_data.http	receive new data from an HTTP source
new_data.mqtt	receive new data from an MQTT source
new_data.ws	receive new data from a WebSocket source
new_data.simulator	receive new data from a Simulator source
rule.state_change	device field state changes caused by rule
task.create	a new task is created
task.ack	a task is acknowledged
task.close	a task marking it as complete or terminated
task.reopen	reopen a previously closed task

Hook example

The JSON object represents a hook example. Using syntax like $(some_name) to use Hook Variable to replace the placeholder.

 {
            "eventType": "task.create",
            "hookType": "webhook",
            "name": "test",
            "baseURL": "https://some_ext_host.com",
            "route": "/route/v1/basic",
            "method": "GET",
            "params": {
                "filter": "extName||$eq||$(extName)}",
                "task_id": "$(id)",
                "category": "$(category)"
            },
            "headers": {
                "Content-Type": "application/json",
                "Authorization": "Bearer $(SECRET_JWT_TOKEN)"
            },
            "data": {
                "desc": "this is the body data to send",
                "call_back_url": "https://my_example_service.com"
            },
            "workspace": "e54421dc-5dd4-4b02-b0ea-262c7a8554dd",
        }

Below, we will break down each field and provide an explanation.

Property	Type	Description
`eventType`	string	The type of event that triggered this hook. In this case, it's "task.create", indicating that the hook was created when a new task was added.
`hookType`	string	The type of hook being used. In this case, it's "webhook", which means the hook will send an HTTP request to another service.
`name`	string	A human-readable name for the hook.
`baseURL`	string	The base URL of the external host that will receive the HTTP request from this hook.
`route`	string	The specific route on the external host that will be targeted by the hook's HTTP request.
`method`	string	The HTTP method (e.g., GET, POST, PUT) that will be used when sending the request to the external host.
`params`	object	An object containing key-value pairs of parameters that will be sent with the hook's HTTP request.
`headers`	object	An object containing key-value pairs of HTTP headers that will be sent with the hook's request.
`data`	object	An object containing key-value pairs of data that will be sent with the hook's request.
`workspace`	string	The ID of the workspace where this hook was created (automatically assigned, not configurable by normal users).

Hook Variable

For EventType `alert.trigger`

Variable	Desc
`id`	Unique identifier of the alert
`category`	Category or type of the alert
`deviceId`	Identifier of the device associated with the alert
`workspace`	Workspace or context where the alert is being performed
`description`	Brief description of the alert
`timestamp`	Date and time when the alert was trigger
`title`	Title of the alert
`location`	Location of the alert

For EventType `task.*`

Variable	Desc
`id`	Unique identifier of the task
`category`	Category or type of the task
`state`	Status or state of the task (e.g., open, closed)
`deviceId`	Identifier of the device associated with the task
`workspace`	Workspace or context where the task is being performed
`description`	Brief description of the task
`openTime`	Date and time when the task was opened
`openBy`	Person who opened the task (email address)
`ackTime`	Array of dates and times when the task was acknowledged
`lastAckTime`	Last date and time when the task was acknowledged
`ackBy`	Array of people who acknowledged the task (email addresses)
`closeTime`	Array of dates and times when the task was closed
`lastCloseTime`	Last date and time when the task was closed
`closeBy`	Array of people who closed the task (email addresses)

For EventType `rule.state_change`

Variable	Desc
`deviceId`	Device id
`deviceType`	Device type
`workspace`	Workspace id
`time`	Date and time when the changes happen
`field`	Field which state changed
`state`	Target state for the field
`message`	Description for the field state changes

For EventType `infer.state_change` or `new_data.*`

Variable	Desc
`id`	Device id
`type`	Device type
`workspace`	Workspace id
`online`	the boolean online status
data field the device has
i.e. `HUMIDITY`,	it will retrived the corresponding value

others veriable

Besides above specify variable per eventType, any seer variable defined in workspace can be used with syntax $().

How it Works​

Benefits​

Supported Event Type​

Hook example​

Hook Variable​

For EventType alert.trigger​

For EventType task.*​

For EventType rule.state_change​

For EventType infer.*state_change* or new_data.*​

others veriable​