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
| Event | Severity | Payload | Payload Example | Description |
|---|---|---|---|---|
WMS_LOADED | INFO | - | - | WMS loaded |
CONFIGURATION_LOADED | INFO | - | - | Config fetched using the provided Config ID |
CAMERA_PERMISSION_GRANTED | INFO | - | - | User granted the camera permission |
CAMERA_PERMISSION_DENIED | ERROR | - | - | User denied the camera permission |
CAMERA_STARTED | INFO | - | - | Camera started. This can be either by user or automatic. |
MEASUREMENT_STARTED | INFO | - | - | Measurement Started. This can be either by user or automatic. |
MEASUREMENT_CREATED | INFO | Measurement ID | { "measurementId": "a1e6c2e6-410b-4e19-bae5-a72a0343d322" } | Measurement was created |
INTERMEDIATE_RESULTS | INFO | SNR, Sequence, Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a", "snr": 100, "sequence": 1} | Intermediate results received |
SCAN_COMPLETED | INFO | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | Scan completed and waiting for the final results |
RESULTS_RECEIVED | INFO | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | Final results received |
REDIRECTING_TO_CALLBACK | INFO | Measurement ID (if created) | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | Starting the redirect to the callback URL |
MEASUREMENT_CANCELED | WARN | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | Measurement was cancelled |
CONSTRAINT_VIOLATION | ERROR | Constraint Violated, Measurement ID (If created) | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | A constraint was violated (resulting in measurement cancellation) |
PAGE_UNLOADED | INFO | Measurement ID (If created) | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | Either the user closed the browser (tab) or navigating away from WMS |
WEBSOCKET_DISCONNECTED | WARN | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | WebSocket disconnected |
WEBSOCKET_RECONNECTED | INFO | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | WebSocket either connected or reconnected |
WEBSOCKET_RECONNECTION_FAILED | ERROR | Measurement ID | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | WebSocket failed to reconnect |
API_ERROR | ERROR | API Error Code, Measurement ID (If created) | { "measurementId": "fbfbec8f-cb05-4288-99e5-5e219648399a" } | API threw an error |
PAGE_VISIBILITY_CHANGE | INFO | Visible / 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_SNR | ERROR | Details | { "details": "LOW_SNR" } | Measurement was cancelled due to low SNR |
GENERAL_ERROR | ERROR | Details | { "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"
},
}
| Field | Description |
|---|---|
timestamp | The time of the event |
sessionId | The session ID provided when constructing the call-in URL |
sequence | The sequence of the event, starts at 0 and incremented with each event |
event | Event code as shown on the list of events |
payload | If 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');