Webhooks

A system hook that extends a function call by an HTTP call under defined conditions.

Table of Contents

Introduction

In order to insert an additional action into the process flow of a functional sequence, the ability for reacting to a function call is required. In yuuvis® Momentum, webhooks are a suitable option for this purpose. They belong to the system hooks and thus are triggered by function calls under specified conditions defined on their predicate attribute.

A webhook extends the function by an HTTP call. Whenever the predicate of a webhook delivers a true result, an optional HTTP call to a web URL defined in the webhook configuration is performed. The process flow is interrupted until the webhook activity is finished. Thus, the webhook can perform additional processing steps before passing the data back to resume the interrupted main process. If the predicate of a webhook delivers a false result, the HTTP call is skipped.

For the additional processing, a custom service has to be implemented. This service must be able to handle the request body and the assigned headers. Please note the maximum header size that should be supported by your custom service.

Import and content update webhooks are called in the Repository service, all others in the API-gateway service.

Any changes to the webhook configuration require a restart of the services that are responsible for the call of the affected functions

Webhook Types

Depending on their type, webhooks are triggered in different situations within the data processing chain.

The webhook type dms.response.objects can be triggered in various situations. For some of them there are special webhook types (dms.response.objects.insert, dms.response.objects.update, dms.response.objects.search, dms.response.objects.delete). These sub-webhooks are triggered directly after dms.response.objects.

HTTP Method

Webhook Type

Evaluation Target of the Predicate

Description

Affected Requests
GET

The tenant name of the user who sent the request.

Retrieves roles and any additional available information about the current user logging in to the authentication system from the URL.

 Authentication process

POST

Objects provided by an import request body

This webhook can be triggered by 

  • an object import,
  • an update of the content,
  • an update or the metadata,
  • or a tag update.

POST /api/dms/objects

POST /api/dms/objects/{objectId}
PATCH /api/dms/objects/{objectId}

POST /api/dms/objects/{objectId}/contents/file

POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore (as of 2022 Spring)

POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

DELETE /api/dms/objects/{objectId}/tags/{name}
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true

DELETE /api/dms/objects/{objectId}/contents/file (as of 2023 Summer)

POST
as of 2021 Autumn
dms.request.objects.upsert.database-beforeEnriched objects just before they are indexed

This webhook can be triggered by 

  • an object import,
  • an update of the content,
  • an update or the metadata,
  • or a tag update.

POST /api/dms/objects

POST /api/dms/objects/{objectId}
PATCH /api/dms/objects/{objectId}

POST /api/dms/objects/{objectId}/contents/file

POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore (as of 2022 Spring)

POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

DELETE /api/dms/objects/{objectId}/tags/{name}
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true

DELETE /api/dms/objects/{objectId}/contents/file (as of 2023 Summer)

POSTdms.request.update.metadata (deprecated)Single object in the request body JSON list

Triggers upon metadata updates, before the JSON request body is evaluated and used to update the object.

Can be used to modify or validate the metadata, i.e., to facilitate role-based user authorization.

POST /api/dms/objects/{objectId}

PATCH /api/dms/objects/{objectId}

POSTdms.request.searchIncoming search queries

The search endpoint and any endpoint containing a search request can trigger this webhook. Check the value of the incoming search query parameter.

POST /api/dms/objects/search

POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

POST
(as of 2022 Winter)
dms.request.objects.contentsDMS object as stored in the system including metadata properties, content stream properties and options sections.

A webhook of this type can be triggered by a request for retrieval of a binary content file or a rendition.

Errors with a properly formatted body get the HTTP status code 404.

GET /api/dms/objects/{objectId}/contents/file
GET /api/dms/objects/{objectId}/versions/{versionNr}/contents/file

GET /api/dms/objects/{objectId}/contents/renditions​/text

GET /api/dms/objects/{objectId}/contents/renditions​/pdf
GET /api/dms/objects/{objectId}/versions/{versionNr}/contents/renditions​/pdf

POSTdms.request.objects.deleteThe active version of the object or the specific version that is to be deleted

The webhook is triggered if the object or version to delete exists and is deletable, i.e., if the user has sufficient permissions and if the object is not a non-empty folder.

DELETE /api/dms/objects/{objectId}
DELETE /api/dms/objects

DELETE /api/dms/objects/{objectId}/versions/{versionNr}

POSTdms.response.objectsObjects within a list of objects that is to be returned to the user, i.e., in search queries

Delivers a list of predicate-matching objects to a secondary recipient.

Any request returning an object list triggers this webhook directly before the return. Applies whenever object lists are part of the HTTP response:

  • Search queries
  • Object Iiports
  • Object GETs
  • Object metadata updates
  • Moving content

POST /api/dms/objects

POST /api/dms/objects/{objectId}
PATCH /api/dms/objects/{objectId}
POST /api/dms/objects/{objectId}/contents/file

DELETE /api/dms/objects/{objectId}
DELETE /api/dms/objects

DELETE /api/dms/objects/{objectId}/contents/file (as of 2023 Summer)

DELETE /api/dms/objects/{objectId}/tags/{name}

POST /api/dms/objects/{objectId}/tags/{name}/state/{state}
POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true
POST /api/dms/objects/search
POST /api/dms/objects/{objectId}/actions/move/contents/repositories/{repositoryId}
POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/move/contents/repositories/{repositoryId}

GET /api/dms/objects/{objectId}
GET /api/dms/objects/{objectId}/versions
GET /api/dms/objects/{objectId}/versions/{versionNr}

POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore (as of 2022 Spring)

DELETE /api/dms/objects/{objectId}/versions/{versionNr}

POSTdms.response.objects.insertThe final object after import

Import requests trigger this webhook after successful import directly before the return.

POST /api/dms/objects
POSTdms.response.objects.updateThe object after the update

Update requests trigger this webhook after successful update directly before the return. This concerns content updates, metadata updates and tag updates.

POST /api/dms/objects/{objectId}
PATCH /api/dms/objects/{objectId}

POST /api/dms/objects/{objectId}/contents/file

DELETE /api/dms/objects/{objectId}/contents/file (as of 2023 Summer)

POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore (as of 2022 Spring)

POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

DELETE /api/dms/objects/{objectId}/tags/{name}

POST /api/dms/objects/{objectId}/tags/{name}/state/{state}

POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true

POSTdms.response.objects.deleteThe active version of the object or the specific version that is deleted

This webhook is triggered directly after the successful deletion of a document and after the equivalent AMQP hook, and can for instance inform other systems.

DELETE /api/dms/objects/{objectId}
DELETE /api/dms/objects

DELETE /api/dms/objects/{objectId}/versions/{versionNr}

POSTdms.response.objects.searchSearch result entry

Search requests trigger this webhook if they were successful directly before the return.

POST /api/dms/objects/search

Predicate

The predicate specifies the condition for the call of individual webhooks. It is declared in the webhook configuration.

If multiple webhooks are registered for the same webhook type, the predicate is applied to the original predicate target for each of them and in the order of definition. Imagine an example scenario with two registered webhooks of the type dms.response.objects.search

{
    "enable": true,
    "predicate": "spel:true",
    "type": "dms.response.objects.search",
    "url": <suitable endpoint removing the property 'appEmail:bcc'>,
    "useDiscovery": true
},
{
    "enable": true,
    "predicate": "spel:properties['appEmail:bcc']!=null",
    "type": "dms.response.objects.search",
    "url": <any suitable endpoint>,
    "useDiscovery": true
}

If objects in a search result have the appEmail:bcc property and the first webhook removes this property from the objects, the predicate of the second webhook still matches.

The same behavior holds for the webhook type dms.response.objects and one of its sub-webhook types dms.response.objects.*:

{
    "enable": true,
    "predicate": "spel:true",
    "type": "dms.response.objects",
    "url": <suitable endpoint removing the property 'appEmail:bcc'>,
    "useDiscovery": true
},
{
    "enable": true,
    "predicate": "spel:properties['appEmail:bcc']!=null",
    "type": "dms.response.objects.search",
    "url": <any suitable endpoint>,
    "useDiscovery": true
}

Configuring Webhooks

As a type of system hooks, webhooks are configured in the \service-manager\config\system\systemHookConfiguration.json configuration file within the service manager in JSON format. Any changes to the system hook configuration will not apply until the affected services have been restarted.

>> systemHookConfiguration.json

The timeouts that limit the process time of webhooks in order to avoid system bottlenecks are configured in the application-prod.yml configuration file as shown in the following example:

service:
  connection-timeout-ms: 3000
  socket-timeout-ms: 10000


Loggers for Webhooks

As of version 2022 Spring, the input and output data for each webhook can be monitored via loggers.
>> Logging Configuration

The logging level can be specified

  • for all webhooks, e.g., os.dev.webhooks=DEBUG, or
  • for individual webhook types, e.g., os.dev.webhooks.dms.request.search=DEBUG.

The logging configuration for each webhook has to be read by the service that calls the webhook. For the individual webhook types, different services are responsible. Thus, please ensure that your webhook logging configuration is defined in a configuration file that is read by its calling service. In order to apply the configuration changes, each calling service has to be refreshed or restarted.

Depending on the logging level, the following details are logged:

Logging LevelLogged Information
DEBUG

Only enabled webhooks are considered. The following data are logged:

  • boolean result of the predicate evaluation
  • predicate evaluation target
  • if the predicate is true: input and output data of the webhook including the headers
TRACE

For enabled webhooks, the same information is logged as is the case for the DEBUG logging level.

Disabled webhooks are listed together with the information: Webhook not enabled.

Summary

This article gave an overview of the webhook types that are available in yuuvis® Momentum. Check out the "Preprocessing Metadata using Webhooks" tutorial for an example application which shows different webhook types.


Read on

Preprocessing Metadata using Webhooks

An example Webhook consumer service set up using Java and Spring Boot.  Keep reading

System Hooks

Define additional actions triggered by specified events, extend the functionality of yuuvis® Momentum API. Keep reading

Basic Use Case Flows

Define additional actions triggered by specified events, extend the functionality of yuuvis® Momentum API. Keep reading