Alert Webhook Integration Guide

Alert Webhook Integration Guide

InCloud Manager provides Webhook functionality to help you receive alert notifications in real-time.

1. Configuring Webhook

When registering a Webhook in the Incloud Service alert rule, please provide the following information:
  1. URL (Required): Enter the URL address where your system will receive the alerts, e.g., https://yourdomain.com/webhook-endpoint
  2. Secret Token (Optional): If you want to secure the requests, you can provide a secret key. The system will use this key to generate a signature for each alert request to ensure the security of the request.

2. Webhook Request Description

When device generates an alert, it will send the alert information to the Webhook URL you configured via a POST request. The alert content will be transmitted in JSON format and encoded using UTF-8.

Request Header:

  1. Content-Type: application/json
  2. X-Signature (Optional): If a key is configured, the X-Signature header will contain an encrypted value that is the signature of the request body, generated using the HMAC algorithm and encoded in Base64.
  1. def verify_signature(data: dict, signature: str, secret: str):
  2.     """Verify Webhook Signature
  3.     :param data: Request the json data received
  4.     :param signature: The X-Signature value entered in the request headers
  5.     :param secret: Secret token
  6.     """
  7.     payload = json.dumps(data, ensure_ascii=False).encode()
  8.     if not signature:  # If there is no signature, return True without verification
  9.         return True
  10.     expected_signature = hmac.new(
  11.         secret.encode('utf-8'),
  12.         payload,
  13.         hashlib.sha256
  14.     ).digest()
  15.     expected_signature = base64.b64encode(expected_signature).decode('utf-8')
  16.     return hmac.compare_digest(signature, expected_signature)

Request body (example alert message) :

  1. {
  2.   "oid": "65e6cd35361ee640b6a04ec7",
  3.   "org": {
  4.     "name": "inhand00356",
  5.     "_id": "65e6cd35361ee640b6a04ec7"
  6.   },
  7.   "app": "nezha",
  8.   "type": "reboot",
  9.   "deviceId": "66ea69ab06eccf714c377403",
  10.   "entityId": "66ea69ab06eccf714c377403",
  11.   "entityName": "EF605231726YKLU",
  12.   "data": {
  13.     "ruleId": "677791e7c0015635b5df77aa",
  14.     "reason": "reboot",
  15.     "serialNumber": "EF605231726YKLU",
  16.     "timestamp": "2025-01-06T10:01:38Z"
  17.   },
  18.   "createdAt": "2025-01-06T10:01:38Z",
  19.   "updatedAt": "2025-01-06T10:01:38Z",
  20.   "ack": false,
  21.   "deviceGroupId": "66ea775522b4cd7a3dda4005",
  22.   "deviceGroup": {
  23.     "name": "605",
  24.     "_id": "66ea775522b4cd7a3dda4005"
  25.   },
  26.   "_id": "677baa025a34db68978609b8"
  27. }

Field description:

Field

Type

Description

_id

string

Alert ID.

ack

boolean

Whether the alarm has been confirmed.

app

string

Application of ownership.

content

string

Alert content.

data

object

Alert details.

data.serialNumber

string

The device serial number of the alert.

data.reason

string

Alert type.

data.retention

string

Time left to trigger an alarm (how long the license is left to generate an alert, how long offline to generate an alert, in seconds).

data.timestamp

string

Alert generation time

deviceId

string

The ID of the alarm device

entityId

string

An alert entity.

entityName

string

Alert entity name

entityType

string

Alert entity type.

oid

string

The id of the organization to which the alarm belongs.

org

object

Organization information.

org._id

string

Organization id.

org.name

string

Organization name.

title

string

Alert title.

type

string

Alert type.

updatedAt

date

The update time of the alert.

createdAt

date

The create time of the alert.

deviceGroupId

string

The group id of the device.

deviceGroup

object

Group.

deviceGroup._id

string

Group id.

deviceGroup.name

string

Group name.

closedAt

date

Alert close time.

status

string

Alert status: active, closed.

priority

int

Alert priority.


Alert type：

Alert type

InCloud Manager alert type

connected

Connect to Platform

disconnected

Disconnect from Platform

config_sync_failed

Configuration Sync Failed

sim_switch

SIM Switch

local_config_update

Configuration Modified Locally

reboot

Reboot

firmware_upgrade

Firmware Changed

license_expiring

License Expiring Soon

license_expired

License Expired

uplink_switch

Primary Uplink Switch

ethernet_wan_connected

Wired WAN Connected

ethernet_wan_disconnected

Wired WAN Disconnected

modem_wan_connected

Cellular Wan Connected

modem_wan_disconnected

Cellular Wan Disconnected

wwan_connected

Wi-Fi(STA) Wan Connected

wwan_disconnected

Wi-Fi(STA) Wan Disconnected

client_connected

Client Online

client_disconnected

Client Offline

cell_traffic_reach_threshold

Cellular Usage Threshold Reached

bridge_loop_detect

Loop Detection

cell_operator_switch

Carrier Switched

uplink_status_change

Link Up/Down

Retry Mechanism:

When network errors or request timeouts occur, the request may fail. The system will automatically retry the request until the maximum retry limit is reached or the request is successful. The default retry count is 3, with a 10-second interval between retries.

Note: Retries will not be triggered when the service cannot be reached, such as in cases of DNS resolution errors, service shutdown, etc.

3. Push Validation

If no secret token is configured, there is no need to validate the signature.

If a secret token is configured, you can validate the signature using the following steps:

  • Calculate the Signature: When you receive the Webhook request, you need to recalculate the signature of the request body using the same secret token and algorithm that were configured.
  • Compare the Signature: Compare the signature you calculated with the X-Signature value in the request header. If they match, it indicates the request is from InCloud Manager, and you can safely process it.

4. Successful Request Response

When your Webhook endpoint successfully receives and processes the alert, it should return an HTTP 200 OK status code.

If request processing fails, return the appropriate error status code (e.g., 400 or 500) and ensure that the error information is properly logged.

Notes:

  • It is strongly recommended to use HTTPS to ensure secure data transmission.
  • If a secret token is configured, always verify the X-Signature to ensure the request is from a trusted source.
  • Ensure the Webhook endpoint returns an HTTP 200 OK status code, indicating the alert has been successfully processed.

By following the above steps, you can efficiently and securely receive and process InCloud Manager alert Webhook events.

    • Related Articles

    • Alert Webhook Integration Guide

      Device Manager provides Webhook functionality to help you receive alert notifications in realtime. 1. Configuring Webhook When registering a Webhook in the Device Manager alert rule, please provide the following information: URL (Required): Enter the ...

    • AI Assistant User Guide

      This document introduces the capabilities and usage guidelines of the InCloud Manager AI Assistant. Note: This feature is currently in public beta. Stay tuned for the official release. Overview The InCloud Manager AI Assistant is an intelligent ...

    • InLink User Guide

      1. InLink Introduction InLink is a cloud platform created by InHand Networks that is dedicated to SIM card management, aimed at providing users with convenient, fast, and secure SIM card management services. We offer the following services: Real-time ...

    • Device Manager User Manual

      1.About the Platform Device Manager ("DM") is an Internet of Things (IoT) device management cloud platform of the "new generation" independently developed and operated by InHand. With visual user interfaces (UIs) and easy-to-use processes, it allows ...

    • InCloud Manager User Manual

      About the platform The InCloud Manager is a cloud-based network management platform. Integrating InHand edge routers and AP, it helps enterprises build a modern network environment and quickly realize digital retail and office. InCloud Manager ...