Changelog
GitHubAirthings DashboardTerms & conditions

Webhooks - Subscribing to all locations

Previously, configuring a webhook for specific locations required manual action and updates whenever a new location was added to an account. Now, you can configure webhooks to subscribe always to all locations in an account. See the sections below for more details.

Dashboard

You can configure webhooks in our dashboard at dashboard.airthings.com/integrations/webhooks:

Previously, the Select all checkbox did not account for new locations added in the future. Now, the Select all option automatically includes new locations as they are added.

API

Our API also enables webhook configuration. We have introduced a new field, subscribedToAll, which allows a webhook to subscribe to all locations. When this field is set to true, it is no longer possible to provide specific locations in the request. See our API reference for more information or see this example: 

curl --request POST \
     --url 'https://ext-api.airthings.com/v1/webhooks?accountId=00000000-0000-0000-0000-0000000000' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $AUTH_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "active": true,
  "eventTypes": [
    "samle-feed"
  ],
  "subscribedToAll": true,
  "url": "https://webhook.site/00000000-0000-0000-0000-0000000000",
  "name": "My Webhook"
}
'

API - Added ability to update device labels in batch

🚀 Feature Release

Updating/creating device labels in batch is now possible via API. This new endpoint requires the access scope write:device. It allows 1000 operations per request.

You can look at API Spec for further details.

Webhooks - Hourly Radon Added

We added support for hourly radon also to webhooks known as hourly-radon-sample-feed. The sample-feed provides a 24-hour average, and sometimes it can be useful to subscribe to hourly events. The event feed is opt-in so it's necessary to update existing webhooks to use it. 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). 

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

API - Hourly Radon added

🚀 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

Webhooks - Added Ventilation Rate Events

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.

Webhooks - Improved occupancy feed

✨ 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.

Webhooks - Deprecating subscribing to single devices

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": []
}

Webhooks - Configuration UI improvement

✨ 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.