What are webhooks?
Webhooks push event data in real-time to an external service. While our public REST API allows you to pull data from us, Webhooks continuously stream events of your sensors to an endpoint you provide, enabling you to process and integrate our data into your system.
Similar to our REST API, Webhooks send event data in a JSON format via HTTP(S).
Ideally, the endpoint should listen to an HTTPS connection. If that is not possible, or for additional security, we generate a secret key that you can use to validate Webhook requests.
How to set up a webhook?
You get to the events Webhook page by going to Settings and selecting Connect integrations.
On the first screen, you need to provide the endpoint of your service that receives the Webhook requests and choose an authentication method. You have two options:
Send key in headers - we will send the secret key in the header (
x-infogrid-secret-key) of each Webhook request. You can validate the request by making sure the header value matches your local copy of the secret key (next step)Send signature in headers - instead of sending the secret key, we send an HMAC signature (
x-infogrid-signature) of the request alongside the signature algorithm (x-infogrid-signature-algorithm). More details follow below.
After entering the URL and choosing the secret key option, click on “Generate Secret Key”.
You can now copy the secret key by clicking on the link. Resetting the URL will delete the key.
If you want to temporarily stop sending event data, you can toggle the “active” switch, which will disable the Webhook until it is switched back on again.
How to receive event data?
The service receiving the event 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 a future iteration we will retry sending the event in case of a failure, but currently any other HTTP status codes are ignored and events are only sent out once regardless of the answer).
Events have the following format:
Header
Example:
x-infogrid-signature: some-hash-value
x-infogrid-signature-algorithm: sha512
Payload
The payload contains two fields:
a
typefield, which currently can only beeventsan
eventsfield, which is an array of sensor events. Currently, only one event per Webhook request is sent (in a future iteration when we introduce batching, more than one event can be sent in a single request)
Example:
{
"type": "events",
"events": [{
"event_id": "DTE:temperature:cc32jqmqbcjs5d1qkvh0-0",
"profile_id": "00000000-0000-0000-0000-00000000dfb9",
"source_id": "DTE:bt3nk63853cg00fll8c0",
"timestamp": "2022-08-24T14:59:50.196000Z",
"type": "temperature",
"value": 21.55,
"server_timestamp": "2022-08-24T14:59:50.196000Z"
}]
}
How to validate webhook requests?
You can validate webhook requests in two ways, depending on how you configure the Webhook as mentioned above: either by a) comparing the secret value we send in the header with your local copy, or b) by validating the request signature.
The following is an explanation about validating the request signature.
Each request sent from our Webhook contains two custom headers:
x-infogrid-signaturewith the signature hash.x-infogrid-signature-algorithmwith the name of the algorithm that has been used to generate the HMAC signature
We generate the request signature by creating an HMAC hex digest of the payload. Using the secret key and the cryptographic hash function specified in the headers (e.g. SHA-512).
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 hash algorithm used
signature_algorithm = request.headers["x-infogrid-signature-algorithm"]
# 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=signature_algorithm,
).hexdigest()
# Check if the signature is valid
return expected_signature == received_signature
Hints & Tips
Use the serialized request payload directly.
Calculate an HMAC hexdigest of the serialized payload, using the webhook secret and algorithm that you retrieve from the request header.
Check that the calculated HMAC matches the signature in the HTTP header
x-infogrid-signature.
Please note that this is a beta version of the feature, and as such there may be some functionality missing, including automatic retries in case of a failed webhook request.