Event types

Webhooks can be configured to send all available event types or specific ones. The configuration is made when adding or editing a webhook, either using the Dashboard or the API.

This page provides information about the different event types, example data, and what the data means.

All webhooks follow the same base structure:

{
	"id": "{Unique ID for the webhook}",
	"type": "{The event type for the webhook}",
	"source": "{URL to the webhook configuration in the Dashboard}",
	"dataContentType": "application/json",
	"labels": {},
	"data": [],
	"time": "{ISO 8601 timestamp}",
	"specVersion": "{Webhook specification version}"
}

The data object will contain the relevant information published by the event. For sample-events, there is a timestamp (recorded) included in the data object, and the delta between this and the timestamp on the webhook (time) will vary based on the relay device's (Space Hub's) connection to the cloud. If the Hub is connected to Ethernet, it will send data from connected devices to the cloud immediately when it is received, but if it uses cellular connection, it will buffer messages from connected devices and send them to the cloud every 5 minutes.

Hub Metadata Feed

The hub-meta-data-feed provides data from Airthings for Business Space Hubs whenever they send the data to the cloud. Hubs sends data to the cloud every hour if they are online, so these events can be used both to identify that the Hubs are connected to the cloud, and to get information about the devices connected to the Hubs.

Example data:

{
	"id": "cca4e4c8-da9d-4e82-98e0-d997adff5f8a",
	"type": "airthings-webhook-cloudevent-hub-meta-data-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/3ae27258-314e-41ae-98ca-ae1702eea68d?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2820006349",
			"recorded": "2023-07-05T13:09:43",
			"lastSeenDevices": [
				"2969013284",
				"3110004513",
				"2920016285",
				"2930117404"
			],
			"devices": {
				"2930117404": {
					"lastSeen": 1688562583,
					"rssi": -46,
					"type": "wavePlus"
				},
				"3110004513": {
					"lastSeen": 1688562583,
					"rssi": -51,
					"type": "spaceCo2Mini"
				},
				"2969013284": {
					"lastSeen": 1688562583,
					"rssi": -81,
					"type": "viewPlusBusiness"
				},
				"2920016285": {
					"lastSeen": 1688562583,
					"rssi": -76,
					"type": "waveMini"
				}
			},
			"connectionType": "cellular"
		}
	],
	"time": "2023-07-05T13:09:43.673535",
	"specVersion": "0.2"
}

The lastSeenDevices array lists the serial number of nodes who has recently used the Hub as a relay device to send data to the Airthings cloud. The devices object provides a list of every device with the following information for each device:

Field	Description
`lastSeen`	Epoch timestamp for when the device last published data
`rssi`	RSSI of SmartLink connection presented in dBm
`type`	Type of device

The data also contains the type of connection (connectionType) the Hub uses to reach the cloud, which can be either cellular or ethernet.

Sample Feed

The sample-feed provides samples from the physical sensors in devices. The event is triggered whenever the device posts data to the cloud.

Example data:

{
	"id": "03f79e5c-65c7-4d82-9311-e576dbc3b7a9",
	"type": "airthings-webhook-cloudevent-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/af241adc-42c6-4a68-8517-9f8601fe58e7?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "3110000280",
			"recorded": "2024-01-03T08:09:05Z",
			"temp": 20.8,
			"pressure": 990.1,
			"humidity": 20,
			"co2": 612,
			"soundLevelA": 26,
			"rssi": -52,
			"batteryPercentage": 99,
			"ratings": {
				"humidity": "POOR",
				"temp": "GOOD",
				"pressure": "GOOD",
				"co2": "GOOD"
			},
			"sensorUnits": {
				"humidity": "pct",
				"temp": "c",
				"pressure": "hpa",
				"soundLevelA": "dbspl",
				"co2": "ppm"
			}
		}
	],
	"time": "2024-01-03T08:09:20.704964Z",
	"specVersion": "0.2"
}

The data object includes the serial number of the device, a timestamp for when the samples were recorded, and all the sensors with their sampled values. There is also a ratings object which includes Airthings' rating of the different sensor values compared to the recommended values for optimal indoor air quality. The sensorUnits object provides a list of the measurement unit each sensor value is presented in.

Mold Sample Feed

The mold-sample-feed provides samples from the mold risk indicator virtual sensor. The event is triggered whenever the virtual sensor is calculated.

Example data:

{
	"id": "00000000-0000-0000-0000-0000000000",
	"type": "airthings-webhook-cloudevent-mold-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "0000000000",
			"recorded": "2023-10-02T20:00:00Z",
			"mold": 1,
			"ratings": {
				"mold": "GOOD"
			},
			"sensorUnits": {
				"mold": "riskIndex"
			}
		}
	],
	"time": "2023-10-02T20:00:00.0Z",
	"specVersion": "0.2"
}

The data object includes the serial number of the device, a timestamp for when the sample was calculated, and the calculated mold risk. There is also a ratings object which includes Airthings' rating of the calculated mold risk compared to when actions should be taken to avoid mold growth. The sensorUnits object provides information about the measurement unit the sensor value is presented in.

Virus Risk Sample Feed

The virus-risk-sample-feed provides samples from the virus risk indicator virtual sensor. The event is triggered whenever the virtual sensor is calculated.

The interval where samples are calculated is every 1 hour, and the sample is calculated based on the last 1 hour of data.

Example data:

{
	"id": "ee0cb906-3dd8-4766-a130-4312620f0406",
	"type": "airthings-webhook-cloudevent-virus-risk-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/3ae27258-314e-41ae-98ca-ae1702eea68d?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2969015904",
			"recorded": "2023-07-06T07:00:00",
			"virusRisk": 1.0,
			"ratings": {
				"virusRisk": "GOOD"
			},
			"sensorUnits": {
				"virusRisk": "riskIndex"
			}
		}
	],
	"time": "2023-07-06T07:17:56.405297",
	"specVersion": "0.2"
}

The data object includes the serial number of the device, a timestamp for when the sample was calculated, and the calculated virus risk. There is also a ratings object which includes Airthings' rating of the calculated mold risk compared to when actions should be taken to avoid mold growth. The sensorUnits object provides information about the measurement unit the sensor value is presented in.

Hourly Radon Sample Feed

The hourly-radon-sample-feed provides calculated hourlyRadon average. The value can be in Bq/m³ or pCi/L and it is possible to configure the preference in webhook configuration (using dashboard or API).

While the radonShortTermAvg sensor in latest samples feed provides a running average of the latest 24 hours, the hourlyRadon sensor presents data processed by an algorithm that uses the data collected from the device to estimate the current Radon level. This can be useful when controlling mitigation equipment or presenting Radon levels in buildings where the ventilation or other mitigation equipment isn't running 24/7. As the name suggests, the value is updated once an hour.

Example data:

{
  "id": "00000000-0000-0000-0000-0000000000",
  "type": "airthings-webhook-cloudevent-hourly-radon-sample-feed",
  "source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000",
  "dataContentType": "application/json",
  "labels": {},
  "data": [
    {
      "serialNumber": "0000000000",
      "hourlyRadon": 0.5,
      "ratings": {
        "hourlyRadon": "GOOD"
      },
      "sensorUnits": {
        "hourlyRadon": "pci"
      },
      "recorded": "2023-11-30T10:00:00Z"
    }
  ],
  "time": "2023-11-30T10:00:00.0Z",
  "specVersion": "0.2"
}

Occupancy Sample Feed

The occupancy-sample-feed provides samples from the occupancy virtual sensor. The event is triggered whenever the virtual sensor is calculated.

Example data:

{
	"id": "fd28e5b5-a1c6-4c99-82fc-b7c73072e852",
	"type": "airthings-webhook-cloudevent-occupancy-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/3ae27258-314e-41ae-98ca-ae1702eea68d?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:15",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:20",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:25",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
    // ... (next 21 objects)
	],
	"time": "2023-07-06T07:19:36.632024",
	"specVersion": "0.2"
}

The data object includes the serial number of the device, a timestamp for when the sample was calculated, and the calculated number of occupants. It will contain 24 objects per device - two hours of data with a 5 minute interval - since the accuracy of the occupancy data improves over this two-hour period. This means that the most recent data will be the least accurate, and the least recent data will be the most accurate.

If information about the size of the room where the device is placed is entered in the Airthings for Business Dashboard, occupantsUpper and occupantsLower will be available in addition to a more accurate occupants value. The upper and lower values are an estimation of the accuracy from the occupancy calculation, and represents the potential lowest and highest amount of occupants detected in the room.

The sensorUnits object provides information about the measurement unit the sensor value is presented in.

Ventilation Rate Feed

The ventilation-sample-feed provides samples from the ventilation rate virtual sensor. The event is triggered whenever the virtual sensor is calculated.

{
	"id": "991a1559-a83f-450b-b001-deb5f36510a6",
	"type": "airthings-webhook-cloudevent-ventilation-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/af241adc-42c6-4a68-8517-9f8601fe58e7?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2930047924",
			"recorded": "2024-07-05T10:40:00Z",
			"airflow": 98.93,
			"airExchangeRate": 4.46,
			"sensorUnits": {
				"airExchangeRate": "ach",
				"airflow": "m3h"
			}
		},
		{
			"serialNumber": "2930047924",
			"recorded": "2024-07-05T10:45:00Z",
			"airflow": 98.93,
			"airExchangeRate": 4.46,
			"sensorUnits": {
				"airExchangeRate": "ach",
				"airflow": "m3h"
			}
		},
		{
			"serialNumber": "2930047924",
			"recorded": "2024-07-05T10:50:00Z",
			"airflow": 98.93,
			"airExchangeRate": 4.46,
			"sensorUnits": {
				"airExchangeRate": "ach",
				"airflow": "m3h"
			}
		},
		// ... (next 21 objects)
	],
	"time": "2024-07-05T12:43:34.134355Z",
	"specVersion": "0.2"
}

If information about the size of the room where the device is placed is entered in the Airthings for Business Dashboard, airFlow will be available in addition the airExchangeRate value.

Airly Sample Feed (deprecated)

The airly-sample-feed provides samples from Airly devices connected to the Airthings for Business Account. The event is triggered whenever samples from the specific Airly device is received by Airthings.

Example data:

{
  "id": "00000000-0000-0000-0000-0000000000",
  "type": "airthings-webhook-cloudevent-airly-sample-feed",
  "source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000?version=v2",
  "dataContentType": "application/json",
  "labels": {},
  "data": [
    {
      "serialNumber": "ARL0000000",
      "recorded": "2023-11-30T10:00:00Z",
      "outdoorHumidity": 73,
      "outdoorPm10": 28,
      "outdoorPm1": 13,
      "outdoorPm25": 22,
      "outdoorPressure": 1002.8,
      "outdoorTemp": -2.5,
      "ratings": {
        "outdoorPm25": "FAIR",
        "outdoorPm1": "FAIR",
        "outdoorPm10": "FAIR",
        "outdoorPressure": "GOOD"
      },
      "sensorUnits": {
        "outdoorPm25": "mgpc",
        "outdoorPm1": "mgpc",
        "outdoorPm10": "mgpc",
        "outdoorHumidity": "pct",
        "outdoorTemp": "c",
        "outdoorPressure": "hpa"
      }
    }
  ],
  "time": "2023-11-30T10:00:00.0Z",
  "specVersion": "0.2"
}