Webhook Messages
SUMMARY Get familiar with the message format and the payloads for various webhook topics.
Message Format
Each webhook topic can have a slightly different format.
Most webhooks have the following structure where the event_details
are the payload of events,
as follows:
{ "topic": "webhook-topic", "events": [ {"EVENT DETAILS": "...."}, {"EVENT DETAILS": "....", ... ] }
Payload Structure
All webhook messages are in JavaScript object notation (JSON) format and include the following information in the header, which describes the configuration of the message itself. The header information appears before the payload in the message. If you configure a custom header in the webhook configuration, it also appears here.
POST /uri/... HTTP/1.1 Host: hooks.abc.com:443 User-Agent: Mist-webhook Content-Type: application/json Content-Length: 382 X-Mist-Signature: ce3af7760f1289d02bf6a7ad19f3xxxxxxxxxx
Infrastructure Payload Examples
For the full list of Webhooks samples, see API Sample Webhooks. This will show you sample webhook messages that the Mist Cloud sends for each of the given webhooks topics.
The following are just some of the webhook samples, starting with the infrastructure webhooks.
Alert
This alert (alarm) example displays a detected rogue AP, the count (number of times Juniper Mist detected it), and the AP and the basic service set identifier (BSSIDs) that detected it.
{ "topic": "alarms", "events": [ { "aps": [ "5c5b35xxxxxx" ], "bssids": [ "00024axxxxxx", "5c5b3xxxxxx", "000f2xxxxxx", "c03f0exxxxxx", "e091f5xxxxxx", "e894f6xxxxxx", "40169fxxxxxx", "40169fxxxxxx", "c03f0exxxxxx", "5c5b35xxxxxx" ], "count": 16, "id": "95193bda-1fef-4ea6-xxxx-xxxxxxxxxxxx", "last_seen": 1549068720, "ssids": [ "qwerty", "A-Dot", "xfinity", "alpha" ], "timestamp": 1549068202, "type": "rogue-ap-detected", "update": true, "org_id": "2818e386-8dec-2562-xxxx-xxxxxxxxxxxx", "site_id": "4ac1dcf4-9d8b-7211-xxxx-xxxxxxxxxxxx" } ] }
Audit
This example is an audits alert indicating that John Doe updated a device. It shows the organization (org_id) and site (site_id) the device belongs to.
{ "topic": "audits", "events": [ { "admin_name": "john doe john.doe@juniper.net", "device_id": "00000000-0000-0000-1000-5c5b35xxxxxx", "id": "8e00dd48-b918-4d9b-xxxx-xxxxxxxxxxxx", "message": "Update Device \"Reception\"", "org_id": "2818e386-8dec-2562-xxxx-xxxxxxxxxxx", "site_id": "4ac1dcf4-9d8b-7211-xxxx-xxxxxxxxxxxx", "src_ip": "xx.xx.xx.xx", "timestamp": 1549047906.201053 } ] }
Client Join
This client-join message displays the MAC address of the client that joined. It also displays the associated connection details the instant a client joins a wireless network.
{ "topic": "client-join", "events": [ { "ap": “5c5b35d0xxxx", "ap_name": “AP43 Test", "band": "5", "bssid": "5c5b35dfxxxx", "connect": 1592333828, "connect_float": 1592333828.324, "mac": "70ef0071xxxx", "org_id": "6748cfa6-4e12-11e6-xxxx-xxxxxxxxxxx", "rssi": -54, "site_id": "d761985e-49b1-4506-xxxx-xxxxxxxxxxx", "site_name": "Test", "ssid": "Mist", "timestamp": 1592333828, "version": 2 "wlan_id": "6c0c0b07-0d77-44d1-xxxx-xxxxxxxxxxxx", } ] }
Client Sessions
The client-sessions payload displays detailed information regarding the entire session from a client to a single AP.
{ "topic": "client-sessions", "events": [ { "ap": “5c5b352fxxxx", "ap_name": “AP43 Test", "band": "5", "bssid": "5c5b352bxxxx", "client_family": "iPhone", "client_manufacture": "Apple", "client_model": "8+", "client_os": "13.4.1", "connect": 1592333548, "connect_float": 1592333548.117, "disconnect": 1592333828, "disconnect_float": 1592333828.589, "duration": 279.835049793, "mac": "70ef00xxxxxx", "next_ap": "5c5b35d0xxxx", "org_id": "6748cfa6-4e12-11e6-xxxx-xxxxxxxxxxxx", "rssi": -87, "site_id": "d761985e-49b1-4506-xxxx-xxxxxxxxxxx", "site_name": "Test", "ssid": "Mist", "termination_reason": 3, "timestamp": 1592333828, "version": 2 "wlan_id": "6c0c0b07-0d77-44d1-xxxx-xxxxxxxxxxxx", } ] }
Device Events
The device-events payload displays details about the device experiencing the event with the reason.
{ "topic": "device-events", "events": [ { "audit_id": "a8ec4d8a-4da6-4ead-xxxx-xxxxxxxxxxx", "ap": "5c5b35xxxxxx", "ap_name": "AP41 Near Lab", "device_name": "AP41 Near Lab", "device_type": "ap/switch/gateway", "ev_type": "NOTICE", "mac": "5c5b35xxxxxx", "org_id": "2818e386-8dec-2562-xxxx-xxxxxxxxxxxx", "reason": "power_cycle", "site_id": "4ac1dcf4-9d8b-7211-xxxx-xxxxxxxxxxxx", "site_name": "Site 1", "text": "event details", "timestamp": 1461220784, "type": "AP_RESTARTED" } ] }
Device Updowns
The device-updowns webhook is a subset of the device-events webhook. It sends only the basic information of the device and reason (type) it went down.
{ "topic": "device-updowns", "events": [ { "org_id": "2818e386-8dec-2562-xxxx-xxxxxxxxxxxx", "site_id": "4ac1dcf4-9d8b-7211-xxxx-xxxxxxxxxxxx", "type": "AP_RESTARTED", "ap": "5c5b35xxxxxx", "ap_name": "AP01", "site_name": "Site1" "timestamp": 1461220784 } ] }
Juniper Mist Edge Events
The mxedge-events webhook payload can contain basic information about an event occurring on an individual Juniper Mist Edge device similar to device-events.
{ "topic": "mxedge-events", "events": [ { "audit_id": "03a65fa8-f74b-4c82-xxxx-xxxxxxxxxxxx", "mxcluster_id": "27558fe2-a0e5-4236-xxxx-xxxxxxxxxxxx", "mxedge_id": "00000000-0000-0000-1000-xxxxxxxxxxxx", "mxedge_name": "ME1", "org_id": "dfb3a656-2a21-4ea5-xxxx-xxxxxxxxxxxx", "timestamp": "1692974834.308884", "type": "ME_CONFIG_CHANGED_BY_USER" } ] }
Location Payload Examples
The next group is the Location webhooks, which are available only for sites (not organizations).
- Location Coordinates
- Occupancy Alerts
- RSSI Zone
- SDK Client Scan Data
- Virtual Beacon Entry and Exit Event
- Zone Entry and Exit Events
Location Coordinates
The location webhook payload correlates client information to a location on a map (floorplan) uploaded to Juniper Mist. An accurately scaled map and use of the SDK client are requirements for this webhook.
{ "topic": "location", "events": [ { "site_id": "4ac1dcf4-9d8b-7211-xxxx-xxxxxxxxxxxx", "map_id": "845a23bf-bed9-e43c-xxxx-xxxxxxxxxxxx", "x": 13.5, "y": 3.2, "timestamp": 1461220784, // for SDK client "type": "sdk", "id": "de87bf9d-183f-e383-xxxx-xxxxxxxxxxxx", "name": "optional", // for WIFI "type": "wifi", "mac": "5684daxxxxxx", // Optional for wifi "wifi_beacon_extended_info": [ {"frame_ctrl": 776, "seq_ctrl": 772, "payload": "............"}, ] // for ASSET "type": "asset", "mac": "7fc293xxxxxx", "ibeacon_uuid": "f3f17139-704a-f03a-xxxx-xxxxxxxxxxxx", "ibeacon_major": 13, "ibeacon_minor": 138, "eddystone_uid_namespace": "2818e3868decxxxxxxxx", "eddystone_uid_instance": "5c5b35xxxxxx", "eddystone_url_url": "https://www.abc.com", "mfg_company_id": 935, "mfg_data": "648520a1020000", "battery_voltage": 3370 } ] }
Occupancy Alerts
The occupancy-alerts webhook displays information about specific zones if they exceed the configured occupancy_limit.
{ "topic": "occupancy-alerts", "events": [ { "alert_events": [ { "current_occupancy": 10, "map_id": "f5d26c7f-1670-4921-xxxx-xxxxxxxxxxxx", "occupancy_limit": 5, "org_id": "6748cfa6-4e12-11e6-xxxx-xxxxxxxxxxxx", "timestamp": 1594861457, "type": "COMPLIANCE-VIOLATION", "zone_id": "b83312a7-7269-4ae1-xxxx-xxxxxxxxxxxx", "zone_name": "PLM and Leadership" }, { "current_occupancy": 20, "map_id": "f5d26c7f-1670-4921-xxxx-xxxxxxxxxxxx", "occupancy_limit": 10, "org_id": "6748cfa6-4e12-11e6-xxxx-xxxxxxxxxxxx", "timestamp": 1594861457, "type": "COMPLIANCE-VIOLATION", "zone_id": "80acf542-e863-43cf-xxxx-xxxxxxxxxxxx", "zone_name": "CSQA" }, { "current_occupancy": 9, "map_id": "f5d26c7f-1670-4921-xxxx-xxxxxxxxxxxx", "occupancy_limit": 4, "org_id": "6748cfa6-4e12-11e6-xxxx-xxxxxxxxxxxx", "timestamp": 1594861457, "type": "COMPLIANCE-VIOLATION", "zone_id": "a4c7a7c2-880e-4a0e-xxxx-xxxxxxxxxxxx", "zone_name": "Marketing & Sales Ops" } ], "site_id": "67970e46-4e12-11e6-xxxx-xxxxxxxxxxxx", "site_name": "MIST OFFICE" } ] }
RSSI Zone
The rssizone webhook payload displays devices that have exceeded a configured minimum RSSI threshold across a site.
{ "topic":"rssizone", "events":[ { "mac":"500291xxxxxx", "map_id":"f5d26c7f-1670-4921-xxxx-xxxxxxxxxxxx", "rssizone_id":"e38f8e76-40db-4144-xxxx-xxxxxxxxxxxx", "site_id":"f5fcbee5-fbca-45b3-xxxx-xxxxxxxxxxxx", "timestamp":1694158990.986472, "trigger":"enter", "type":"wifi" } ] }
SDK Client Scan Data
The SDK Client Scan Data webhook payload displays specific data about a client that isn’t available without installing an application (using the SDK) on the client itself.
{ "events": [ { "connection_ap": "5c5b35xxxxxx", "connection_band": "2.4", "connection_bssid": "5c5b35xxxxxx", "connection_channel": 11, "connection_rssi": -87, "last_seen": 1592333828, "mac": "70ef00xxxxxx", "scan_data": [ { "ap": "5c5b35xxxxxx", "band": "2.4", "bssid": "5c5b35xxxxxx", "channel": 11, "rssi": -87, "ssid": "mist-wifi", "timestamp": 1592333828 }, { "ap": "5c5b35xxxxxx", "band": "5", "bssid": "5c5b35xxxxxx", "channel": 36, "rssi": -75, "ssid": "mist-wifi", "timestamp": 1592333828 } ], "site_id": "d761985e-49b1-4506-xxxx-xxxxxxxxxxxx" } ], "topic": "sdkclient-scan-data" }
Virtual Beacon Entry and Exit Event
The vbeacon webhook is triggered when a mobile device running the Juniper Mist SDK is entering or exiting the area defined by a virtual beacon.
{ "topic":"vbeacon", "events":[ { "mac":"10521cxxxxxx", "map_id":"5a8b84e6-cc7b-xxxx-xxxxxxxxxxxx", "site_id":"f5fcbee5-fbca-45b3-xxxx-xxxxxxxxxxxx", "timestamp":1694166602.662786, "trigger":"enter", "type":"wifi", "vbeacon_id":"ca301fd7-07af-4d42-xxxx-xxxxxxxxxxxx" } ] }
Zone Entry and Exit Events
The zone webhook is triggered when a device enters or exits a defined zone.
{ "topic":"zone", "events":[ { "mac":"10521cxxxxxx", "map_id":"5a8b84e6-cc7b-xxxx-xxxxxxxxxxxx", "site_id":"f5fcbee5-fbca-45b3-xxxx-xxxxxxxxxxxx", "timestamp":1694166602.662786, "trigger":"exit", "type":"wifi", "zone_id":"b83312a7-7269-4ae1-xxxx-xxxxxxxxxxxx " } ] }