Webhook - Set value

Prerequisites

Modules

• osp-web

• osp-cli

Checkout branches

git checkout origin/osp-cli-configuration .
git checkout origin/osp-web .

Note

The complete example can be checkout from any OnSphere stack

Description

In this tutorial you will learn how to create a webhook endpoint with an API key and convert the content to an OnSphere value.

Two endpoints are configured :

• /example-boolean

• /example-json

Then values of different types are associated with the endpoints.

Configuration structure

Steps

1. Setup a user with an API key

   To set a webhook value, the user must be member of the groups /internal/data-access

   modules/keycloak/keycloak-1/users.keycloak

   {
     "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"
         }
       }
     ]
   }
   

   This API key will be used to authenticate the emitter of the HTTP POST requests and its user access rights will be applied.

   Warning

   When defining an API key for a user, it may take up to 1 minute for it to be applied.

2. Create two webhook endpoints

   root/webhook/boolean-endpoint/endpoint.webhook

   {
       "moduleId": "modules.web.web-1",
       "path": "/example-boolean"
   }
   

   root/webhook/text-endpoint/endpoint.webhook

   {
       "moduleId": "modules.web.web-1",
       "path": "/example-json"
   }
   

3. Configure triggers for boolean value

   root/webhook/boolean-endpoint/boolean-value/owner.webhook

   {
       "linkedEndpoint": "root.webhook.boolean-endpoint"
   }
   

   root/webhook/boolean-endpoint/boolean-value/value.ospp

   {
       "name": "Boolean example",
       "description": "Example of boolean value from json",
       "type": "BOOLEAN",
       "retention": "STEADY"
   }
   

4. Configure triggers for json value

   root/webhook/text-endpoint/boolean-value/value.ospp

   {
       "name": "Boolean example",
       "description": "Example of boolean value from json",
       "type": "BOOLEAN",
       "retention": "STEADY"
   }
   

   root/webhook/text-endpoint/decimal-value/value.ospp

   {
       "name": "Decimal example",
       "description": "Example of decimal value from json",
       "type": "DECIMAL",
       "retention": "STEADY"
   }
   

   root/webhook/text-endpoint/json-value/value.ospp

   {
       "name": "Wind",
       "description": "Example of extracting a field",
       "type": "TEXT",
       "retention": "FIRE_AND_FORGET"
   }
   

   root/webhook/text-endpoint/json-value/owner.webhook

   {
       "linkedEndpoint": "root.webhook.text-endpoint",
       "fieldName": "alert.information.wind"
   }
   

   Note

   The value will attempt to extract the field alert.information.wind from the JSON body and make it available as an integer. If the content is not in JSON format or if the content does not contain the expected field, an error will be produced instead.

5. Send an HTTP POST request

   Using an HTTP client of your choice, you can now send an HTTP POST request to the webhook and see the result by subscribing on the two values created earlier. The HTTP request should look something like this :

   POST http://stack-1.onsphere.local:5000/osp/webhooks/text HTTP/2.0
   Accept: application/json
   Content-Type: application/json
   Authorization: Bearer simple-api-key
   
   {
   "alert": {
       "temperature": 30,
       "temperature-decimal": 3.5,
       "unit": "degrees",
       "error": true,
       "information" : {
           "wind": "strong"
       }
   }
   }
   

6. Visualize the change with osp-cli

   See OnSphere CLI