Webhooks

Capabilities

Capability	Support	Comment
HTTPS support		See configure webhook
Updating a value		See updating a value. For receiving data from external source
Extracting a field type		See updating a value
Extracting a sub-object json-type
Return data to external source

Authentication method

Type	Support	Comment
Bearer		See Bearer token
Signature Authentication		Hmac256 algorithm only. See HMAC

Examples

• Setting value from external

Concept

Webhook allow an external system to provide data or trigger an action on OnSphere.

Configure webhook

Access to webhook

Webhooks listen for HTTP/HTTPS POST requests on configurable HTTP/HTTPS endpoints, on the same address and port as the dashboard. The endpoints path is updated to add the common prefix /osp/webhooks and the webhook name.

Example :

https://stack.onsphere.ch/osp/webhooks/my-first-webhook

Configure API key

An API key must be provided in the Authorization header. That API key must be associated with a user on Keycloak using the attribute apiKey and the user must have enough access-rights to access the webhook endpoint (this can be achieved using standard OnSphere access rights management).

The user must be member of the /internal/data-access group to access to internal values and setting an api-key

{
  "users": [
    {
      "enabled": true,
      "groups": [
        "/internal/data-access"
      ],
      "username": "example",
      "email": "example@localhost",
      "firstName": "example",
      "lastName": "example",
      "credentials": [
        {
          "initial": true,
          "temporary": true,
          "type": "password",
          "value": "mysuperpassword"
        }
      ],
      "attributes": {
        "authorizedKeys": [],
        "apiKey": "simple-api-key"
      }
    }
  ]
}

Authentication

Authentication use api-key configured in previous section. This section describe supported methods to authenticate a request using it.

Bearer token

Request authentication by adding the header Authorization: Bearer {key}:

Accept: application/json
Authorization: Bearer simple-api-key
Content-Type: application/json

Here is an example using curl cli tool to trigger a boolean value to false :

curl -H "Content-Type: application/json" -H "Authorization: Bearer simple-api-key" -H "Accept: application/json" -d "false" https://stack.onsphere.ch/osp/webhooks/my-first-webhook

HMAC

Request authentication by Hmac signature. X-Hub-Signature-256: sha256={hmac_sum}:

Accept: application/json
X-Hub-Signature-256: sha256=3BSccvSzDGsEl1ip5Vd8cL7eUFFQfsiqz1SblIrQ9dg=
Content-Type: application/json

Generate the signature using following algorithm sample:

signature = 'sha256=' + HMAC256(api-key, body).toBase64().toString('utf-8')

Updating a value

Concept

Webhook permit to push data inside a value

Usage

The content (body) of HTTP/HTTPS POST requests on webhooks is made available to OnSphere using standard Value. If the body is in JSON format, the content of a specific field of the body can be extracted and can be made available as the content of the Value.

Typically, the full body of a webhook request will be made available for alarm/alert-like triggers.

Type	Type of value provided by webhook
BOOLEAN
TEXT
NUMERIC
DECIMAL

Extraction rules

JSON text inside the body of the POST request will be converted into a value. There are some options to select the data :

• Using the field name separated by dot to select one field.

• Using field[INDEX] with an index permit to access element inside an JSON array, if INDEX

  • empty: first element of the array

  • number: element at index from the beginning starting at 0

  • negative number: element from the end starting at -1

Return error

The system always returns 200 code.

Warning

Known bug : There is no type checking about the pushing of a value. This means pushing the text “hello” inside a BOOLEAN value is accepted. Internal Swissdotnet tracking issue #1148

Events based value

If the value is used with FIRE_AND_FORGET retention, the value will reflect an event. Typical usage are creating an alarm, or trigger a script when the call is done.

State based value

If the value is used with STEADY retention, the value will be persisted and reflecting the last call on the webhook. Typical usage are setting a state inside OnSphere.

Examples

• Setting value from external