Blackout Webhooks
Polling for data can be inefficient for both the producer and consumer. We, therefore, provide a simple means of subscribing to specific events.
To enable Webhooks, go again to the developer section in the dashboard's administration area. The types of events are being expanded as we get feedback from users.
The Webhook management section (found below the API keys section)
Webhooks fire a POST HTTPS request to the given Callback URL whenever a chosen event type is fired.
Events include:
- Blocking status changes
- Configuration changes of the organisation (e.g. a new Schedule)
- New Flagged events
The data in the request's body will have the following format, where event_type is either blocking, flags, or config_changed. The value of the field event will contain data specific to the event in question.
Webhook blocking events
Whenever a user is blocked or unblocked, this event will fire, including the device and user IDs for reference. This can be used in conjunction with API-based blocking, as discussed above, to create a closed loop of control.
{
"event_type": "blocking",
"event_time": "2023-05-02T09:01:54.598665Z",
"event": {
"user_id": 1052,
"device_id": 1643,
"new_blocking_state": false
}
}
Webhook new flagged events
Flags are events considered potentially 'bad' behaviour by the device or user. These can include permissions required to detect restrictions (like WiFi, Bluetooth, or Location) or to detect behaviours (like the manual switch being toggled or the device not being seen for some time). Each flag type shows the direction of compliance based on the old_valence to new_valence values (e.g. GOOD to BAD, demonstrating that a device has entered a bad state).
{
"event_type": "flags",
"event_time": "2023-04-27T20:36:11.149202Z",
"event": [
{
"type": "ios_state",
"entity_name": "bluetooth_setting",
"old_state": "poweredOn",
"old_valence": "GOOD",
"new_state": "poweredOff",
"new_valence": "BAD",
"device_id": 4,
"created_at": "2023-04-27 20:36:11",
"updated_at": "2023-04-27 20:36:11",
"entity_id": null,
"flag": "bluetooth_setting"
}
]
}
Webhook configuration change
Currently, this alerts only that something has changed, either to the entire organisation or a set of users based on tags (via the scope field). In the future, this will expand to be more explicit.
{
"event_type": "config_changed",
"event_time": "2023-04-27T20:06:14.801702Z",
"event": {
"scope": "organisation"
}
}