Webhooks

To provide more visibility and information about the events happening after the user is redirected to WMS, we offer an optional Webhook facility.

In order to opt-in to receive the events via a webhook, you need to provide a URL for the webhook which will be added to the Config ID along with an assigned MAC secret for validation.

If a Config ID has a webhook associated with it, events will be sent to the webhook as they happen. The events will be sent in the body of a POST call to the webhook.

Events

EventSeverityPayloadPayload ExampleDescription
WMS_LOADEDINFO--WMS loaded
CONFIGURATION_LOADEDINFO--Config fetched using the provided Config ID
CAMERA_PERMISSION_GRANTEDINFO--User granted the camera permission
CAMERA_PERMISSION_DENIEDERROR--User denied the camera permission
CAMERA_STARTEDINFO--Camera started. This can be either by user or automatic.
MEASUREMENT_STARTEDINFO--Measurement Started. This can be either by user or automatic.
MEASUREMENT_CREATEDINFOMeasurement ID{ "measurementId": "a1e6c2e6-410b-4e19-bae5-a72a0343d322" }Measurement was created
INTERMEDIATE_RESULTSINFOSNR, Sequence, Measurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a", "snr": 100, "sequence": 1}Intermediate results received
SCAN_COMPLETEDINFOMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }Scan completed and waiting for the final results
RESULTS_RECEIVEDINFOMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }Final results received
REDIRECTING_TO_CALLBACKINFOMeasurement ID (if created){ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }Starting the redirect to the callback URL
MEASUREMENT_CANCELEDWARNMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }Measurement was cancelled
CONSTRAINT_VIOLATIONERRORConstraint Violated, Measurement ID (If created){ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }A constraint was violated (resulting in measurement cancellation)
PAGE_UNLOADEDINFOMeasurement ID (If created){ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }Either the user closed the browser (tab) or navigating away from WMS
WEBSOCKET_DISCONNECTEDWARNMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }WebSocket disconnected
WEBSOCKET_RECONNECTEDINFOMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }WebSocket reconnected
WEBSOCKET_RECONNECTION_FAILEDERRORMeasurement ID{ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }WebSocket failed to reconnect
API_ERRORERRORAPI Error Code, Measurement ID (If created){ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" }API threw an error
PAGE_VISIBILITY_CHANGEINFOVisible / Hidden, Measurement ID (If created){ "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a", "state": "VISIBLE" }User minimized / maximized the browser or switched to another tab / application
LOW_SNRERRORDetails{ "details": "LOW_SNR" }Measurement was cancelled due to low SNR
GENERAL_ERRORERRORDetails{ "details": "CAMERA_START_ERROR" }There was an error in starting the camera

Event body

{
  "timestamp": 1689684577,
  "sessionId": "ryueiwoqfh910fu3rpqruvfiu",
  "sequence": 0,
  "event": "MEASUREMENT_CREATED",
  "severity": "INFO",
  "payload": {
    "measurementId": "f0c8ca8d-111d-4dcf-a69d-46ed39a2db06"
  },
}
FieldDescription
timestampThe time of the event
sessionIdThe session ID provided when constructing the call-in URL
sequenceThe sequence of the event, starts at 0 and incremented with each event
eventEvent code as shown on the list of events
payloadIf the event has a payload, it will be provided in the payload section. Example: Measurement ID, SNR etc.

Webhook Validation

A hash of the body contents using the hook's MAC secret (macSecret) is given in the X-WMS-Content-MAC header. The recipient can verify this value to make sure that the webhook call was initiated by WMS by doing the following computation (in JavaScript, for example):

// Note: Use the provided MAC secret here
const hmac = require('crypto').createHmac('sha256', macSecret);
hmac.update(requestBody.toString(), 'ascii');
const expectedContentHmac = 'hmac-sha256=' + hmac.digest('hex');

Note

The Webhook URL needs to be set up at your end and shared with the Nuralogix team in order to update it in your Config ID.