πŸš€ Feature Release

The "Hourly Radon" sensor is now available for the Space Plus devices, and is an improvement of the short term average data that has been the only way to interpret Radon values until now. While the radonShortTermAvg sensor provides a running average of the latest 24 hours, the hourlyRadon sensor presents data processed by an algorithm which 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.

We added "hourly radon" samples to the latest-samples endpoints:

... and new endpoints for historical samples:

Now, there is a new property in the response:

  • hourlyRadon - hourly average radon level

We added a new webhook event type ventilation-sample-feed that provides samples from the ventilation rate virtual sensor. The event is triggered whenever the virtual sensor is calculated.

The data contains airflow in cubic meters per hour and number of air exchanges per hour as airExchangeRate:

{
	"id": "00000000-0000-0000-0000-0000000000",
	"type": "airthings-webhook-cloudevent-ventilation-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "0000000000",
			"recorded": "2024-07-08T20:00:00.0Z",
			"airflow": 98.93,
			"airExchangeRate": 4.46,
			"sensorUnits": {
				"airExchangeRate": "ach",
				"airflow": "m3h"
			}
		},
		// ... (next 23 samples)
	],
	"time": "2024-07-08T20:00:00.0Z",
	"specVersion": "0.2"
}

You can subscribe to this event using the dashboard or the API. See more about the event type here in the webhook documentation.

✨ Improvements

The purpose of our webhook event types is to deliver data as soon as it's generated in the Airthings platform with minimal latency and maximum performance. For this reason, the "occupancy-sample-feed" currently provides only the most recent occupancy data points. The algorithm providing the occupancy data does however calculate occupancy for the past two hours every time it runs - the reason for this being that the accuracy of the sensor improves over time when it has more data to digest. This means that webhook clients currently rely on using the API to collect the most accurate occupancy data from the history endpoint.

Since some of our webhook clients don't have an active API connection, we'd like to offer all the available data from the occupancy sensor in the webhook feed. This means that you will now receive 24 datapoints (2 hours of data with a 5 minute interval) from each device's occupancy sensor instead of 1 when subscribing to the occupancy data feed. The format of the data remains the same, with additional data objects added in the data array:

{
	"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"
			}
		}
	],
	"time": "2023-07-06T07:19:36.632024",
	"specVersion": "0.2"
}
{
	"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"
}

"occupantsUpper" and "occupantsLower" data points will still only be available if room size information has been added to the space containing the device.

We deprecated support for subscribing to single devices. In the future, only subscribing to locations will be supported.

For example, it is recommended to not provide devices in EXT-API endpoint POST ext-api.airthings.com/v1/webhooks:

{
  "name": "webhook with locations only",
  "url": "https://webhooks.airthings.com/samples",
  "locations": ["...", "..."]
  // Deprecated: "devices": []
}

✨ Improvement

Most clients either include all locations in an account or specific locations when configuring a webhook. The option to select specific devices included in the configuration has been available, but since it is rarely used by anyone, we made the decision to remove it.

The configuration list that previously looked like this:

Will now look like this:

This change will greatly improve the user experience when managing webhooks in an account with a high amount of buildings and devices.

✨ Improvements

The content field in the latest events on the webhook configuration page on the Dashboard has been removed. The data provided in the field did not offer any useful information and was causing unnecessary data transfer. The latest events now includes the following fields:

✨ Improvements

Webhook Latest Event Object
The "content" field has been removed from the "mostRecentEvents" object returned from requests to webhooks-related endpoints. We identified that the field did not offer any valuable information, while it was also causing unnecessary data transfer. The latest event object now only includes the following fields:

{
  "hookId": "string",
  "correlationId": "string",
  "url": "string",
  "createdAt": "string",
  "completedAt": "string",
  "updatedAt": "string",
  "statusCode": 0,
}

πŸ› Fixes

Battery History Before Provided Time Range

When using the GET /devices/{serialNumber}/battery endpoint with both query parameters start and end provided, the response could include battery history before the provided time range. This has now been fixed.

The issue was present only when using the start and end parameters together and with relatively low-time ranges (e.g., 10 hours). It was a fallback mechanism to ensure that the response always includes the latest battery status. The fallback mechanism has now been removed. You can increase the time range or use the latest battery endpoint to fetch the latest battery status.

πŸ’₯ Breaking change

As a part of improving and introducing a major update on our Webhook service, we've updated the payload format for hub-meta-data-feed events. The main change is that the value of the "data" key is now an array instead of an object. The reason for this change is to;

  1. Improve consistency between the event types, as all other events follow this format
  2. Allow more data to be sent in one Webhook, to reduce the amount of events you receive.

Here, is the updated the payload posted from the new webhook system.

{
  "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"
}

πŸ“ Documentation

We have updated the documentation of Webhook Event Types with the latest payload change (see above) regarding Hub Metadata feed.