Webhook - Set value

🟡 Intermediate

variable webhook

osp-web osp-cli

This example shows how to create a webhook endpoint secured with an API key that receives HTTP POST requests and maps their payload to OnSphere values.

• Create a user with an API key assigned to the /internal/data-access group.

• Define webhook endpoints that accept HTTP POST requests and forward the payload.

• Map endpoint payload fields to OnSphere values of different types (boolean, numeric, decimal, JSON).

• Extract nested JSON fields from the request body and expose them as typed values.

git checkout origin/osp-web-configuration .
git checkout origin/osp-cli-configuration .
git checkout origin/example-webhook-set-value-all-types .

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",
       "methods": [
           { "verb": "POST" }
       ]
   }
   

   root/webhook/text-endpoint/endpoint.webhook

   {
       "moduleId": "modules.web.web-1",
       "path": "/example-json",
       "methods": [
           { "verb": "POST" }
       ]
   }
   

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",
       "extraction" : {
           "path":  "alert.information.wind",
           "type": "JSON"
       }
   }
   

   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 :

   cURLwgetHTTPieHTTP

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

6. Visualize the change with osp-cli

   See OnSphere CLI