FAQ

How to secure the receiving endpoint?

We support adding static headers to the request, you can also add a hash to the url. You configure this when setting up the hooks at dashboard.airthings.com/integrations/webhooks. You can validate the request on the receiving side using the test button in webhook form on that same page.

How to design the receiving endpoint?

The webhooks expect an acknowledgement within 3 seconds after the post occurred. The receiving side needs to be designed having this in mind. Authorizing and responding (status code: 200 or 204) to the request needs to be done almost instantly. It is recommended to do any calls to databases or integrations in an asynchronous way. Also in a serverless architecture it would be important to keep the function warm, example

What happens if the receiving side is unavailable?

The webhook will fail silently, you can see the status of the last POST at dashboard.airthings.com/integrations/webhooks . The POST will not be retried, but the data is stored in the Airthings platform and can be accessed through other means: API and Dashboard.

How fresh is the data POST from the webhooks?

The data is forked out from our ingestion pipeline quite early, so it will be new. Delay from when the sensor registered the values can be somewhere in the range of 5-10 minutes if synced through an Airthings Hub.

What rate of POSTs are to be expected?

A hub syncs every five minutes and the webhook pipeline currently segments on serial number, so approximately:

1 x Request per Device per 5 Minutes

Where devices are selected during setup of the hook.

NOTE: This rate may change as the api evolves.

Can I create a webhook for all my locations?

Yes it is possible to select multiple locations during the setup of the webhook.

How do I know if a webhook sample is coming from the old or new system?

The payloads coming from the new system have a ?version=v2 in the source field of the payload, the payloads coming from the old system do not.