Logo of the PureLife brand of PureSec GmbH
API docs by Redocly

PureLife Cloud Webhooks (2.9.0)

Download OpenAPI specification:Download

PureSec GmbH: info@puresec.de URL: https://smart-altern.de/

PureLife Cloud Webhooks

Webhook API description for communication between PureLife Cloud service and another system, for machine processing.

Authentication

There are different methods supported for authentication. Each method is based on a token, which is automatically generated by the PureLife cloud for each created webhook. The token is based on a z-base-32 encoded UUID-v4.

For JWT, always the algorithm HS256 is used with the token as the key.

Signing

For each webhook an optional Secret-Key can be defined. If such a key has been provided, the webhook payload is signed with the key via HMAC-SHA256. The signature is encoded in hexadecimal and sent with a sha256= prefix as X-Purelife-Cloud-Signature header.

Sender:

  1. hash = HMAC-SHA256(key, payload)
  2. enc = HEX_encode(hash)
  3. headerKey = "sha256=" + enc
  4. Request with header: X-Purelife-Cloud-Signature: headerKey

Receiver:

  1. enc = Split key for header X-Purelife-Cloud-Signature and remove prefix (sha256=)
  2. headerHash = HEX_decode(enc)
  3. payloadHash = Generate hash the same way as sender
  4. Compare if headerHash == payloadHash

Other information

More information can be found in the PureLife Cloud documentation at Integration.

webhooks

When creating a webhook, you can select the format in which the webhook will be sent. The format defines the content and structure of the data.
Currently three formats are supported:

  • PureSec - Contains a lot of data. Can be used for bot as well as customer webhooks. Supports all events.
  • Custom 1 - A small webhook with selected data. Can only be used for bot webhooks.
  • Raw sensor data - Transmits the received sensor data directly. Structure and contents change frequently. Difficult further processing.

PureSec Webhook | POST

Webhook, which is sent by the PureLife Cloud when a new event occurs.

Authorizations:
BearerAuthApiKeyAuthJWTAuth
Request Body schema: application/json
required

Data object representing the state detected by a sensor. If the webhook was sent because of a rule, the rule is part of the request.

One of
required
object

Information about the PureLife Cloud sending the webhook.

required
object

Information about the webhook

required
object

Event because of which the webhook was created.

required
object

Data of the sensor that sent the event.

required
object or null

Data of the customer to which the sensor belongs. If the sensor does not belong to any customer, the value is null. However, in most cases it can be assumed that the value is present.

required
object

Rule which triggered the webhook

Responses

Request samples

Content type
application/json
Example
{
  • "service": {},
  • "webhook": {
    },
  • "event": {
    },
  • "sensor": {
    },
  • "customer": {
    },
  • "rule": {
    }
}

Custom 1 Webhook | POST

Webhook, which is sent by the PureLife Cloud when a new event occurs.

Authorizations:
BearerAuthApiKeyAuthJWTAuth
Request Body schema: application/json
required

Data object representing the state detected by a sensor.

One of
sensorId
required
string = 26 characters

Unique ID of the sensor (device ID). Always has the prefix id_.

sensorName
required
string [ 1 .. 128 ] characters

Name of the sensor in PureLife Cloud system.

location
string or null [ 1 .. 256 ] characters

Location of the sensor in the PureLife Cloud system.

description
required
string [ 1 .. 256 ] characters

Description of the event in German.

title
string non-empty

The title of the rule as set in the frontend.

Always sent if the event was sent due to a rule. Not sent for customer webhooks.

message
string non-empty

The message of the rule as set in the frontend.

Always sent if the event was sent due to a rule. Not sent for customer webhooks.

createDate
required
integer <int64>

Time at which the event was created by the sensor. Format: milliseconds since Unix epoch (UTC).

Array of objects

The coordinates of the event scaled to the range [0, 1]. The point (0 | 0 | 0) is the lower-left corner and the value (1 | 1 | 1) the upper-right corner. Is always sent if the event contains coordinates.

eventType
required
integer <int32>
Enum: 1 2 5 6 7 10 11 20 21

Type of event. Indicates the state that the sensor has detected.

  • 1 - A fall has probably been detected (Permission required)
  • 2 - The fall has been confirmed
  • 3 - The sensor was wrong or the person got up again before the fall was confirmed (Permission required)
  • 4 - Deprecated: The fall detection cycle was completed or the person got back up after the fall was confirmed
  • 5 - The sensor was inactive and now sends events. It is active.
  • 6 - The sensor was active and is now no longer sending events. It is probably inactive or there are connection problems.
  • 7 - High sensitivity is activated and a fall for it has been confirmed.
  • 10 - The sensor detection range has been left
  • 11 - The sensor detection range has been entered
  • For 20 and 21 choose For region

Responses

Request samples

Content type
application/json
Example
{
  • "sensorId": "id_MzA6QUU6QTQ6RTM6ODQ6NUM",
  • "sensorName": "Anlage #25 - Bad",
  • "location": "Idstein",
  • "description": "Es wurde wahrscheinlich ein Sturz erkannt",
  • "title": "Attention John,",
  • "message": "Your sensor in the kitchen has detected a fall.",
  • "createDate": 1629968058856,
  • "normalizedCoordinates": [
    ],
  • "eventType": 1
}

Raw sensor data Webhook | POST

Webhook, which is sent by the PureLife Cloud when a new event occurs. Events as received from the sensor, without any processing by the PureLife Cloud.
This format is more suitable for experimental purposes and should not be used in a production environment.

Depending on the sensor firmware version, the events do not contain a device ID, and it is up to the webhook creator to create a relationship between the webhook request and the sensor.

Authorizations:
BearerAuthApiKeyAuthJWTAuth
Request Body schema: application/json
required

Data object representing the state detected by a sensor.

object

Events as received from the sensor, without any processing by the PureLife Cloud.
The contents of the events may differ depending on the firmware version and settings.

Responses

Request samples

Content type
application/json
{ }