Skip to content

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.

Blocking Changes
{
    "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).

Flagged events
{
    "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.

Config change
{
    "event_type": "config_changed",
    "event_time": "2023-04-27T20:06:14.801702Z",
    "event": {
        "scope": "organisation"
    }
}