What are alert webhooks?
Remember: If you want to access the raw data from devices, you can use our Event webhooks.
Alert Webhooks push alert data in real-time to an external service. Webhooks continuously stream alerts from your sensors to an endpoint you provide, enabling you to process and integrate our data into your system.
Similar to our REST API and Event Webhooks, Alert Webhooks send alert data in a JSON format via HTTP(S).
How to set up a webhook?
Get in touch with our Customer Success to set up the configuration for Alert Webhooks.
How to receive alert data?
The service receiving the Alert data needs to be able to accept HTTP POST requests. Upon reception, the service should answer promptly with an HTTP 200 OK status to signal that the event has been received. In case of any other response codes the request is retried multiple times with backoff for a maximum of 2 hours which should be enough for temporary outages such as deploys, scheduled maintenance, etc. In case of a longer outage we can also manually replay the failed webhook requests to fill in the missing data.
The requests will have the following format:
Header
Example:
content-type: application/json
x-infogrid-signature: <some-hash-value>
where some-hash-value is the signature generated using the SHA-256 hash function.
Payload
The payload contains three fields:
an
eventfield that contains the basic information about the alert, such as the type of the alert event (alert_start,alert_endoralert_acknowledged) and which sensor it belongs to. This information is also sent over the Events webhook as an eventan
alertfield that contains all the information about the specific alert such as conditions and descriptionsa
sensorfield that gives additional detail about the sensor that this alert was triggered for
Alert start example
{
"event": {
"event_id": "8889c897-c72a-45bf-bdb8-9c69aa9db7e1",
"profile_id": "00000000-0000-0000-0000-0000000000c3",
"timestamp": "2022-01-20T04:23:05.000000Z",
"type": "alert_start",
"value": {
"sensor_profile_id": "00000000-0000-0000-0000-0000000000c3",
"alert_application_id": "82d80ee8-a44c-403c-b879-e5ac8bdcd268",
"alert_id": "45622a1c-72b2-4f7d-89a5-975907c93dd7",
"criteria": ""
}
},
"alert": {
"alert_uuid": "45622a1c-72b2-4f7d-89a5-975907c93dd7",
"alert_duration": ["2022-01-20T04:23:05.000000Z", null],
"alert_acknowledged": null,
"sensor_state": "amber",
"alert_configuration": {
"uuid": "8dfac72d-cf59-45d2-81b8-b081be0f847c",
"name": "Example alert",
"conditions": [
{
"description": "Humidity is less than 30.0%RH",
"period": null,
"operand": "value",
"operator": "less_than",
"operand_args": {},
"reading_type": "humidity",
"operator_args": [0.3]
}
],
},
"sensor": {
"uuid": "00000000-0000-0000-0000-0000000000c3",
"device_name": "IAQ_2930020246",
"name": "Example IAQ sensor",
"description": null,
"type": "airQuality",
"sub_type": null,
"labels": ["Example", "Documentation"],
"location": ["Infogrid International", "Country", "City", "Building X", "Floor Y", "Space Z"]
}
}
}How to validate Alert webhook requests?
You can validate Alert webhook requests by validating the request signature.
Each request sent from our Webhook contains a custom header:
x-infogrid-signaturewith the signature hash.
We generate the request signature by creating an HMAC hex digest of the payload, using the secret key and the cryptographic hash function SHA-256.
To validate the signature, you create the signature the same way and compare the results.
The following is an example in Python:
import hmac
def validate_request_signature(request: Request, secret: str) -> bool:
# Retrieve the signature
received_signature = request.headers["x-infogrid-signature"]
# Retrieve the payload body from the request
payload: bytes = request.body
# Calculate the signature
expected_signature = hmac.new(
secret.encode("utf-8"),
payload,
digestmod="sha256",
).hexdigest()
# Check if the signature is valid
return expected_signature == received_signature