Webhooks module

Edition DX Core

License

MLA

Issues

MGNLHOOK

Maven site

Webhooks

Latest

1.0-beta

The Webhooks module allows you to configure and use webhooks, user-defined callbacks which make REST calls to external APIs, usually to build pipelines.

For an overview about the Webhooks feature in Magnolia, see the Webhooks feature page.

Magnolia Webhooks is a DX Core feature that is currently available as a developer preview. The Webhooks module is provided only for testing purposes in a preproduction beta version.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.webhooks</groupId>
  <artifactId>magnolia-webhooks-core</artifactId>
  <version>1.0-beta</version>
</dependency>

The module requires at least the following dependencies, which will be included automatically if you use Maven to add the module to your webapp.

<dependency>
  <groupId>io.vavr</groupId>
  <artifactId>vavr</artifactId>
</dependency>
<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-core</artifactId>
</dependency>
<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-retry</artifactId>
</dependency>

Configuration

All webhook definition Yaml files should be placed in the webhooks directory of your light module.

Properties

Property name Description

name

required

Name of the webhook.

The name must be unique across all webhook definitions.

url

required, if there is no associated REST client referenced through the restClientName property (see below).

The URL of the target endpoint that is notified when an event occurs.

method

required, if no associated REST client is referenced.

The HTTP method used when Magnolia connects to the target endpoint for an event.

Supported methods: GET, POST, PUT, DELETE and PATCH.

queryParameters

optional

Key-value map with the parameters to be sent as:

  • A query string in a GET request.

  • A body in a POST or PUT request.

headers

optional

Key-value map with the headers to be sent with an HTTP request.

Example
headers:
  "Content-Type": "application/json"
  "X_Custom_Header": "value"

restClientName

required, if the url and method properties are not configured

Name of an already existing REST client configuration that will be used when a webhook event occurs.

restCallName

required, if the url and method properties are not configured

Name of an already existing REST client call that will be used when a webhook event occurs.

enabled

required

Boolean value which enables or disables the webhook.

If false, the target endpoint is not touched.

events

required

Node with a list of webhook events.

A webhook definition must have at least one event definition.
Example
events:
  - name: contentPublished
    eventType: Published
    entity: Content
  - name: contentUnpublished
    eventType: Unpublished
    entity: Content

name

required

Name of a webhook event. The name must be unique across all event definitions in the same file.

eventType

required

Type of the webhook event. Two event type values are allowed at the moment, Published and Unpublished.

  • Published is used when an existing content is published, no matter whether the publication falls under publication workflow or not.

  • Unpublished is used when an existing content is unpublished.

entity

optional

Type of the content.

The value can be either Content or any existing Content Type.

filter

optional

String that allows you to filter the events.

Example
filter: "@path LIKE '%whatever%' or @nodeType = 'mgnl:page'"

The filter grammar expressions are enclosed in parentheses and can be combined using AND and OR.

Filter properties

  • @path - filters by node path.

  • @workspace - filters by node workspace.

  • @nodeType - filters by node type.

  • @recursive - boolean value defining whether the webhook event is recursive (including subpages and subtrees) or not (single publication).

Filter operators

The @path, @workspace and @nodeType filter properties expect a String value and support the =, !=, <> and LIKE operators.

The @recursive filter property supports the =, != and <> operators.

Example configuration

/example-light-module/webhooks/webhookConfig_1.yaml
name: webhook1
url: https://my.server.com/webhookEndpoint
method: GET
queryParameters:
  access_token: '2cf09447'
headers:
  "Content-Type": "application/json"
  "X_Custom_Header": "value"
enabled: true

events:
  - name: contentPublished
    eventType: Published
    filter: "@path LIKE '%foo%' or @nodeType = 'mgnl:page'"
  - name: contentUnpublished
    eventType: Unpublished
    filter: "@path LIKE '%foo2%' or @nodeType = 'mgnl:page'"

Usage

Feedback