Alert Webhook Integration Guide

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 URL address where your system will receive the alerts, e.g., https://yourdomain.com/webhook-endpoint
  • 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:

  • Content-Type: application/json
  • 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": "6527bb9cf2246b000178a1ec",
  3. "deviceId": "67da8c16c351850001bdb5c2",
  4. "deviceName": "RF3151342000003",
  5. "serialNumber": "RF3151342000003",
  6. "ruleId": "67dcfbb33abb850001bbc6c2",
  7. "ruleName": "test",
  8. "alertType": "hourly_traffic_excess",
  9. "notify": {
  10. "users": ["6527bb9df2246b000178a1f0"],
  11. "types": ["webhook", "email"]
  12. },
  13. "alertAt": "2025-03-21T05:52:36Z",
  14. "content": "Your gateway device on the Device Manager platform (gateway name: RF3151342000003, serial number: RF3151342000003) has used 93.66 MB of traffic for SIM2 between 2025-03-21 04:52:36 UTC and 2025-03-21 05:52:36 UTC.",
  15. "updateAt": "2025-03-21T05:52:36Z",
  16. "_id": "67dcfeaa3abb850001bbc6d6"
  17. }

Field description:

FieldType

Description

_id

string

Alert ID.

deviceId

string

The ID of the alert device.

deviceName

string

Device name.

serialNumber

string

The device serial number of the alert.

ruleId

string

Alert rule ID.

ruleName

string

Alert rule name.

alertType

string

Alert type.

notify.users

array

Notify the user.

notify.types

array

Type of notification: email,sms,webhook.

alertAt

date

The create time of the alert.

content

string

Alert content.

updateAt

date

The update time of the alert.

Alert type：

  1. online // Gateway online
  2. offline // Gateway offline
  3. link_change // Interface up/down
  4. link_backup // Link backup
  5. sim_switch // SIM switch
  6. hourly_traffic_excess // Hourly traffic alarm
  7. daily_traffic_excess // Daily traffic alarm
  8. monthly_traffic_excess // Monthly traffic alarm
  9. power_switch // Power type switch
  10. power_fault //  Battery fault
  11. power_recovery //Battery fault recovery

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 Device 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 Device Manager alert Webhook events.

    • Related Articles

    • 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: URL (Required): Enter ...

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