@universis/hooks

Universis API Server module providing webhook functionality.

Installation

npm install @universis/webhooks

Usage

Install service in your Universis API Server configuration:

{
  "services": [
    {
      "serviceType": "@universis/webhooks#WebHookService"
    }
  ]
}

Include @universis/webhooks schema loader under settings/schema:

{
  "schema": [
    {
      "loaderType": "@universis/webhooks#SchemaLoader"
    }
  ]
}

Configuration

The service can be configured with the following options:

{
  "settings": {
    "universis": {
      "webhooks": {
        "logLevel": "info",
        "logDir": "./log"
      }
    }
  }
}

where logLevel can be one of error, warn, info, verbose, or debug and logDir is the directory where logs will be stored.

Features

• Create, read, update, and delete webhooks.
• Trigger webhooks on specific events.

API Endpoints

• GET /api/webhooks/actions: Retrieve a list of available webhook actions. The operation requires webhooks:read permission.
• POST /api/webhooks: Create a new webhook. The operation requires webhooks:write permission.
• GET /api/webhooks: Retrieve a list of webhooks. The operation requires webhooks:read permission.
• GET /api/webhooks/:id: Retrieve a specific webhook by ID. The operation requires webhooks:read permission.
• PUT /api/webhooks/:id: Update a specific webhook by ID. The operation requires webhooks:write permission.
• DELETE /api/webhooks/:id: Delete a specific webhook by ID. The operation requires `webhooks

Create a new webhook

To create a new webhook, send a POST request to /api/webhooks with the following JSON body:

{
  "action": "update_user",
  "active": true,
  "config": {
    "url": "https://example.com/webhook",
    "contentType": "application/json"
  }
}

Delete a webhook

To delete a webhook, send a DELETE request to /api/webhooks/:id, where :id is the unique identifier of the webhook you want to delete. The operation requires webhooks:write permission.

Update a webhook

To update a webhook, send a POST request to /api/webhooks/ containing the updated fields in the JSON body.

{
  "id": "7085b05b-8da6-4004-b5cc-7b204725d63f",
  "action": "update_action",
  "active": false,
  "config": {
    "url": "https://newexample.com/webhook",
    "contentType": "application/xml"
  }
}

The operation requires webhooks:write permission. The active field can be used to enable or disable the webhook wihout deleting it. An inactive webhook will not be triggered during events.

Triggering Webhooks

Webhooks are triggered automatically when the specified action occurs in the system. The payload sent will contain relevant data about the event.

{
  "event": "update_user",
  "entityType": "User",
  "entitySet": "Users",
  "origin": "https://api.example.com",
  "target": {
    "id": "12345"
  }
}

where event is the action that triggered the webhook, entityType is the type of entity involved, entitySet is the collection the entity belongs to, and target contains details about the specific entity.

The payload does not include other metadata except for the target identifier. The webhook receiver can use this identifier to fetch additional details if needed.