Follow these steps to enable Webhooks for your site:
- Access Webhooks through Organization -> Site Configurations.
Here, select the specific API topics you want to be pushed to your server. Fill out the Name, URL, and Secret (optional) for your server in order for Webhooks to push the information out.
Organization & Site Level Webhooks (API)
Webhooks are an intuitive method of collecting data by having real-time events push their information onto a provided URL. Triggering webhook events will automatically send and store relevant details for data analysis. We now have webhooks that can be configured aswebhook topics for both the site and org level using our APIs.
The webhooks are essentially going to be used as our pub-sub model for events and alerts. Previously, we supported webhooks at a site level for location data for Wi-Fi & BLE clients. We have now extended the webhooks for the entire Organization, in addition to the site level, and also added the Device Events ( Device being the Access Point) to monitor status changes, and Audit logs for the Org as well.
The device-events topic provides information of AP up/down, configuration, or restart events.
The audit topic relays information found from your Audit Logs (Organization > Audit Logs) in real-time through a webhook to help admins easily keep track of configurations on their org.
Webhooks available for Site vs for Org
All webhooks are available for configuration at a site level. Currently the UI only displays Location related webhook topics, but through the API you may also configure audit and device-events webhooks at a site level. Org level webhooks are limited to just the audit and device-events and can only be configured using APIs for now.
Example Webhook setups
Reference our API documentation on site webhooks (https://api.mist.com/api/v1/docs/Site#webhooks) to see the correct configuration format. The same schema is used for both site webhooks and org webhooks (https://api.mist.com/api/v1/docs/Org#org-webhooks)
Organization webhook for audits:
{ "name": "Webhook_audits", "url": "http://requestbin.fullcontact.com/1gjj1xf1", "topics": [ "audits" ], "enabled": true, "org_id": "<ORG_ID>", "secret": "" },
Examples of sample output for some audit events will be as follows:
{ "topic": "audits", "events": [ { "admin_name": "Jonathan jonathan@mistsys.com jonathan@mistsys.com", "id": "e90612bd-d3f4-456c-90c4-759907631ecc", "message": "Delete WLAN \"0131_jon\"", "org_id": "<ORG_ID>", "site_id": "<SITE_ID>", "src_ip": "71.93.124.103", "timestamp": 1549049281.790302, "wlan_id": "None" } ] }
{ "topic": "audits", "events": [ { "admin_name": "Jonathan jonathan@mistsys.com jonathan@mistsys.com", "id": "e766d0c1-72a9-4f36-bac8-87ae0dff2958", "message": "Update Site \"Old Site\"", "org_id": "<ORG_ID>", "site_id": "<SITE_ID>", "src_ip": "71.93.124.103", "timestamp": 1549049725.732884 } ] }
{ "topic": "audits", "events": [ { "admin_name": "Jonathan jonathan@mistsys.com jonathan@mistsys.com", "id": "761ee0c5-0a84-4a34-a19d-deadbc958f85", "message": "Update Privilege for \"John Doe John@testing.com\"", "org_id": "<ORG_ID>", "site_id": null, "src_ip": "71.93.124.103", "timestamp": 1549049788.642661 } ] }
Organization webhook for audits AND device-events. You may have multiple topics in a single webhook. All webhook data would be sent to the same URL provided. To separate your topics in different URLs, create a unique webhook for each topic.
{ "name": "Webhook_audits_events", "url": "http://requestbin.fullcontact.com/1awe1xf1", "topics": [ "audits", “device-events” ], "enabled": true, "org_id": "<ORG_ID>", "secret": "" },
Site webhook for device-events:
{ "name": "Webhook_Events", "url": "http://requestbin.fullcontact.com/1gdsj1xf1", "site_id": "<SITE_ID>", "topics": [ "device-events" ], "enabled": true, "org_id": "<ORG_ID>", "for_site": true, "secret": "" }
Some examples of device events include:
"AP_ASSIGNED" "AP_CLAIMED" "AP_CONFIG_CHANGED_BY_RRM" "AP_CONFIG_CHANGED_BY_USER" "AP_CONFIGURED" "AP_CONNECTED" "AP_DISCONNECTED" "AP_RESTART_BY_USER" "AP_RESTARTED" "AP_UNASSIGNED" "AP_UNCLAIMED" "AP_UPGRADE_BY_SCHEDULE" "AP_UPGRADE_BY_USER" "AP_UPGRADED" "AP_UPGRADE_FAILED"
Examples of sample output for some device events will be as follows:
{ "topic": "device-events", "events": [ { "ap": "<AP_MAC>", "org_id": "<ORG_ID>", "site_id": ""<SITE_ID>", "timestamp": 1548096105, "type": "AP_CONFIG_CHANGED_BY_USER" }, { "ap": "<AP_MAC>", "org_id": "<ORG_ID>", "site_id": ""<SITE_ID>", "timestamp": 1548096106, "type": "AP_CONFIGURED" } ] }
{ "topic": "device-events", "events": [ { "ap": "<AP_MAC>", "org_id": "<ORG_ID>", "site_id": ""<SITE_ID>", "timestamp": 1548095894, "type": "AP_DISCONNECTED" } ] }
{ "topic": "device-events", "events": [ { "ap": "<AP_MAC>", "org_id": "<ORG_ID>", "site_id": ""<SITE_ID>", "timestamp": 1548095795, "type": "AP_RESTARTED" }, { "ap": "<AP_MAC>", "org_id": "<ORG_ID>", "site_id": "<SITE_ID>", "timestamp": 1548095795, "type": "AP_CONFIGURED" } ] }
The alarms topic contains many event types, including infrastructure (device offline, restarted), security, and marvis. The content of an alarm webhook will vary by the event. There are a few common fields such as org_id, site_id, timestamp, but many of the fields will vary by event type. If you look at https://api.mist.com/api/v1/const/alarm_defs, that will list the extra “fields” included with each event type.
Here is an example of a device_down event from alarms topic
{
"topic": "alarms",
"events": [
{
"aps": [
"5c5b355003cf",
"5c5b353e4eca"
],
"count": 2,
"group": "infrastructure",
"hostnames": [
"AP1",
"AP2"
],
"id": "d8925edf-3a34-41a7-a90b-c91b7e2c3a10",
"last_seen": "2021-07-07T12:27:51",
"org_id": "9777c1a0-6ef6-11e6-8bbf-02e208b2d34f",
"severity": "warn",
"site_id": "978c48e6-6ef6-11e6-8bbf-02e208b2d34f",
"site_name": "Live Demo",
"timestamp": 1625661567.201274,
"type": "device_down"
}
]
}
Sending Webhooks messages to two different URLs
You may also use multiple Webhooks to send the same message to different URLs – just create multiple Webhooks for the same topics, and direct them to different URLs. Here is an example of two different Webhooks sending the same topics (zone, asset-raw, location) to different URLs.
[
{
"name": "test-2",
"url": "https://entrcm2y9kqd.x.pipedream.net/",
"site_id": "<SITE_ID>",
"topics": [
"zone",
"asset-raw",
"location"
],
"enabled": true,
"org_id": "<ORG_ID>",
"modified_time": 1558116886,
"for_site": true,
"secret": "",
"created_time": 1558116886,
"id": "faba1d29-79f8-48c6-s79a-7c5dcafbeb95"
},
{
"name": "test-1",
"url": "https://en9rwaac2harf.x.pipedream.net/",
"site_id": "<SITE_ID>",
"topics": [
"zone",
"asset-raw",
"location"
],
"enabled": true,
"org_id": "<ORG_ID>",
"modified_time": 1558116568,
"for_site": true,
"secret": "",
"created_time": 1502409129,
"id": "9d8r521b-e283-2d1b-b49c-063105999b51"
}
]
Testing out Webhooks:
If you don’t have a server set up for receiving webhooks, you may do some initial testing with RequestBin, which allows users to inspect the API topics sent out as webhooks. Use RequestBin to do a quick verification that data is being pushed through from our webhooks:
- Navigate to http://requestbin.net and select Create a RequestBin
Deleting Multiple Webhooks
To delete multiple webhooks go to /api/v1/sites/site_id/webhooks/id. You can find the “id” for each webhook at the bottom of the payload. From there you can either delete or edit that specific webhook.
Webhook Payloads
Please reference this API page for example webhook payloads of available events: https://api.mist.com/api/v1/const/alarm_defs