Webhooks

Webhooks for easy integration of external applications into the PureLife Cloud.

The PureLife Cloud uses webhooks to notify your application when a sensor reports a new event. To do this, an HTTP POST request is sent to a stored URL.

Authentication#

With each request, the PureLife Cloud sends an automatically generated token for each webhook. This can be used to verify that the request was sent from the cloud and not from another party.

The token is generated by a cryptographic random number generator and is 128 bits long. To transfer the token easily, it is encoded as z-base-32. You get the token on the overview page for webhooks.

The cloud supports different methods for authentication using the token:

1. Bearer-Authentication: Sends the token as an Authorization: Bearer <token> header.
2. X-Api-Key (IETF RFC): Sends the token as an X-Api-Key: <token> header. The structure of the header name is based on the standard HTTP header.
3. X-API-KEY (Case sensitive): Sends the token as an X-API-KEY: <token> header. Can be used if your application is case sensitive.
4. HTTP/Basic: Uses HTTP basic authentication. The username is always purelife-cloud and the password is the token.

To further secure your application, procedures such as rate limiting and fail2Ban should be used.

Sining#

The cloud can optionally sign the webhook request sent to your application. To do this, an X-Purelife-Cloud-Signature header is added to the request. This verifies that the request was sent from the PureLife Cloud and not from someone else.

In order to sign your requests, a secret must be stored for the webhook.

Verification#

The X-Purelife-Cloud-Signature header in each signed request contains an indication of the hash algorithm and signature used.

X-Purelife-Cloud-Signature: sha256=bdea638cc3e6f6ff70c1e6597f25020028d4975b82528ace6ca0688747f7c255

The cloud generates signatures using a hash-based authentication code (HMAC) with SHA256. Verification is possible with the following steps:

1. Divide the header into two parts with the symbol = to get the hash algorithm used and the signature.
2. Calculate an HMAC with a SHA256 hash function. Use the stored Secret as the secret key and the body of the request as the message.
3. Encode the calculated HMAC as a hexadecimal value.
4. Compare the signature of the header with the calculated signature.

Response#

The cloud does not expect a specific response from the addressed application, but the request should be processed quickly. The cloud waits a maximum of 3 seconds before canceling the request and trying again. If the application fails to process a request within 3 seconds, delivery will not be possible. This is necessary because there can be many requests when connecting many sensors and blocking by the cloud should be prevented.

Status codes#

To simplify error analysis, it is recommended to use the standard HTTP status codes. It is important here that the status code 200 or 201 is sent for a successfully recognized request, otherwise the cloud may interpret the request as an error and repeat it.

Repetition mechanism#

If the cloud is not able to successfully deliver the request to the application, it will try to repeat the request. If it is not possible to deliver the request after the third attempt, it will be rejected. The intervals between the attempts is calculated using an exponential backoff algorithm.

Behavior in case of errors#

If an error occurs, it will be logged internally, but not automatically forwarded to you. If you suspect a problem, contact your administrator.

Structure of the request#

The structure and formatting can be set per webhook.

See: Webhook API-Documentation

Use#

The webhook can be configured as Account-Bot (for use in the rule set) or as Customer-Bot (for independent use) can be created and used.