Webhook

The available webhooks currently provided by VisionMax are:
Enum:[EVENT_TRIGGERED, TRIP_STARTED, TRIP_FINISHED, GPS_UPDATE, ASSET_UPLOADED, TASK_UPDATE]
Note: DEVICE_STATUS_UPDATE is available on the staging environment only.
Each notification delivery expects to receive a '200 HTTP status code' with a JSON response of {'status':'success'}. Otherwise, it will be considered a failed delivery.

• EVENT_TRIGGERED

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "EVENT_TRIGGERED",                        #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "gps": {                                            #object: the gps object
      "lng": "121.374111",
      "lat": "25.047111",
      "alt": "0.0",
      "speed": "0.0",
      "direction": "N"
    },
    "timestamp": 1706745916,                            #number: the timestamp of the reported event
    "event_type": 5,                                    #number: the id of event type
    "event_name": "Start Up",                           #string: the name of event
    "ticket": "4b2afd89-8123-4842-b430-c95fc143b14a",   #string: the ticket of event
    "severity_level": "Minor",                          #string: the severity level of the event, Enum:[`Minor`, `Moderate`, `Severe`]
    "task_id": "cc2afd89-8423-4942-b430-112c9a9e51b6",  #string: remote task ID
    "detail": "URL",                                    #string: follow the URL to retrieve details of the event
    "snapshots": {                                      #object: the snapshot info
        "count": 2,                                     #number: the count of the capture mode of snapshot
        "capture_mode": ["C_F", "C_I"]                  #list: the list of the capture mode of snapshot
    },
    "video": {                                          #object: the video info
        "count": 0,                                     #number: the count of the capture mode of video
        "capture_mode": []                              #list: the list of the capture mode of video
    },
    "nfc": {                                            #object: the nfc info
        "id": "ee565d"                                  #string: the nfc id
    }
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

Speed information in the gps object is represented in meters per second(m/s).

• TRIP_STARTED

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "TRIP_STARTED",                           #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "gps": {                                            #object: the gps object
      "lng": "121.374111",
      "lat": "25.047111",
      "alt": "0.0",
      "speed": "0.0",
      "direction": "N"
    },
    "timestamp": 1706745916,                            #number: the timestamp of the trip's start time
    "detail": "URL"                                     #string: follow the URL to retrieve details of trip
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

Speed information in the gps object is represented in meters per second(m/s).

• TRIP_FINISHED

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "TRIP_FINISHED",                          #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn":"serial number here",                   #string: the serial number of device
    "device_cid":"certificate of device here",          #string: the certificate id of device
    "gps":{                                             #object: the gps object
      "lng": "121.374111",
      "lat": "25.047111",
      "alt": "0.0",
      "speed": "0.0",       
      "direction": "N"
    },
    "timestamp": 1706745916,                            #number: the timestamp of the trip's start time
    "detail": "URL"                                     #string: follow the URL to retrieve details of trip
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

Speed information in the gps object is represented in meters per second(m/s).

• GPS_UPDATE

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "GPS_UPDATE",                             #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "gps": {                                            #object: the gps object
      "lng": "121.374111",
      "lat": "25.047111",
      "alt": "0.0",
      "speed": "0.0",
      "direction": "N"
    },
    "timestamp": 1706745916                             #number: the timestamp of the reported GPS
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

Speed information in the gps object is represented in meters per second(m/s).

• ASSET_UPLOADED

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "ASSET_UPLOADED",                         #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "timestamp": 1706745916                             #number: the timestamp of file creation
    "event_type": 5,                                    #number: the id of event type which the file belongs
    "event_name": "Start Up",                           #string: the name of event which the file belongs
    "ticket": "4b2afd89-8123-4842-b430-c95fc143b14a",   #string: the ticket of event which the file belongs
    "task_id": "cc2afd89-8423-4942-b430-112c9a9e51b6",  #string: the remote task ID of event which the file belongs
    "event_detail": "URL",                              #string: follow the URL to retrieve details of the event which the file belongs
    "file_type": "SNAPSHOT",                            #string: the type of file, Enum:[`NMEA`, `SNAPSHOT`, `VIDEO`]
    "capture_mode": "C_I",                              #string: the capture mode of file
    "file_detail": "URL"                                #string: follow the URL to retrieve details of the file
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

• TASK_UPDATE

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "TASK_UPDATE",                            #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "task_id": "411b64be-4598-4fdc-a0c9-4099bc6417b5",  #string: the task ID
    "state": "ack"                                      #string: the state of task
    "code": "D_S00000",                                 #string: the code for the execution result from the device
    "report_at": 1706745916,                            #string: the timestamp of the task update report
    "desc": "desc here"                                 #string: the description for the execution result from the device
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

• DEVICE_STATUS_UPDATE

  {
  "type": "Notification",                               #string: type of notification
  "hookName": "DEVICE_STATUS_UPDATE",                   #string: the hook name
  "messageId": "msg id",                                #string: the message id
  "message": "{                                         #string: the `json string` of notification message
    "device_sn": "serial number here",                  #string: the serial number of device
    "device_cid": "certificate of device here",         #string: the certificate id of device
    "previous_status": "offline",                        #string: the previous status of device, Enums: `online`, `offline`, `standby`, `waking_up`
    "new_status": "online"                             #string: the new status of device, Enums: `online`, `offline`, `standby`, `waking_up`
    "changed_at": 1706745916,                           #string: the timestamp when device status was changed
    "changed_by": "heartbeat",                          #string: the action that triggered the device status change
    "health": {}                                        #object: the health report of device
  }",                     
  "signature": "signature of the message",              #string: signature of the message
  "kid": "The key id of the signing key"                #string: the key id
  }
  

Each notification delivery expects to receive a '200 HTTP status code' with a JSON response of {'status':'success'}. Otherwise, it will be considered a failed delivery.
Failed notification delivery will be retried up to 12 times with an interval of one hour.
The notification service attaches a signature in the body of every delivered message. The signature is RSA with SHA1.

Verify the message with the signature (optional)

1. Deserialize the JSON body.
2. Retrieve the signature from the field: signature.
3. Retrieve the key ID from the field: kid.
4. Obtain the public key from the webhook-signing endpoint using the key ID from the previous step.
5. Verify the signature with the message field. Note: Do not deserialize the message field because the signature is signed with the JSON string.

Subscribe to the webhook to receive notifications.
If necessary, you can resubscribe to the same webhook to update the target URL.

In order to confirm that the target URL is valid and ready to receive notifications,
the notification service will send a raw POST request to the target URL, and expects to receive a 200 HTTP status code to activate the subscription, regardless of whether the response body is present.
Sample of the raw POST body:

     "type": "Subscription",                     #string: type of notification
     "messageId": "msg id",                      #string: the message id
     "message": "{                               #string: the `json string` of notification message
       "time": "1706745891545478712",
       "hook_name": "GPS_UPDATE",
       "url": "https://sample.com/gps_update"
     }",
     "signature": "signature of the message",    #string: signature of the message
     "kid": "The key id of the signing key"      #string: the key id
   }

Retrieve the public key used for verifying the signatures.

Plain text of the public key.
ex:

-----BEGIN PUBLIC KEY-----
.......
-----END PUBLIC KEY-----