Webhook - Read values via GET

🟢 Beginner

variable webhook

osp-web

This example shows how to expose a webhook endpoint that writes a value with POST, reads it back with GET, and resets it with DELETE — turning the endpoint into a small inbound REST resource.

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

• Define a webhook endpoint declaring POST, GET and DELETE in its methods.

• Link a STEADY value to the endpoint with owner.webhook so it can be read back.

git checkout origin/osp-web-configuration .
git checkout origin/example-webhook-read-reset .

How it works

• The endpoint declares POST, GET and DELETE in its methods list. A request using a verb that is not declared is rejected with a 405 Method Not Allowed.

• A POST writes the request body into the value linked to the endpoint by its owner.webhook file.

• A GET (without a linked script) returns a JSON array of the values exposed by the endpoint, each as { "itemId", "content", "type" }.

• A DELETE resets every exposed value to its initialized (unset) state; a subsequent GET then returns a null content.

• The value uses the STEADY retention so its last written state is retained and can be read back. A FIRE_AND_FORGET value would always read back as null.

See reading values for the full reference.

Steps

1. Setup a user with an API key

   To call the webhook, the user must be a member of the group /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"
         }
       }
     ]
   }
   

   Warning

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

2. Create the webhook endpoint

   The endpoint declares POST, GET and DELETE in its methods list.

   root/webhook/state-endpoint/endpoint.webhook

   {
       "moduleId": "modules.web.web-1",
       "path": "/state",
       "methods": [
           { "verb": "POST" },
           { "verb": "GET" },
           { "verb": "DELETE" }
       ]
   }
   

3. Link a value to the endpoint

   The owner.webhook file links the value to the endpoint; the value itself is configured separately and uses the STEADY retention so it can be read back.

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

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

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

   {
       "name": "State",
       "description": "A value written via POST, read back via GET and reset via DELETE",
       "type": "TEXT",
       "retention": "STEADY"
   }
   

4. Write, read and reset the value

   Write a value with a POST:

   cURLwgetHTTPieHTTP

   curl -X POST http://stack-1.onsphere.local:5000/osp/webhooks/state \
     -H "Authorization: Bearer simple-api-key" \
     -H "Content-Type: text/plain" \
     -d 'hello'
   

   Read it back with a GET:

   cURLwgetHTTPieHTTP

   curl http://stack-1.onsphere.local:5000/osp/webhooks/state \
     -H "Authorization: Bearer simple-api-key" \
     -H "Accept: application/json"
   

   The endpoint answers with 200 and the current value:

   [
       { "itemId": "root.webhook.state-endpoint.state-value", "content": "hello", "type": "TEXT" }
   ]
   

   Reset it with a DELETE; a subsequent GET then returns a null content:

   [
       { "itemId": "root.webhook.state-endpoint.state-value", "content": null, "type": "TEXT" }
   ]