Webhooks module

The information on this documentation page is not yet applicable in production.

Edition

DX Core

License

MLA

Issues

MGNLHOOK

Git

Enterprise / webhooks

Maven site

Webhooks

Latest

2.0-SNAPSHOT

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.

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>2.0-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>info.magnolia.webhooks</groupId>
  <artifactId>magnolia-webhooks-events-ui-api</artifactId>
  <version>2.0-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>info.magnolia.webhooks</groupId>
  <artifactId>magnolia-webhooks-events-jcr</artifactId>
  <version>2.0-SNAPSHOT</version>
</dependency>

Dependencies for CDS and JCR storage

To use CDS (contentDatasource) storage, add the magnolia-webhooks-events-ui-api dependency.
To use JCR as persistence storage, add the magnolia-webhooks-events-jcr dependency.

Additional dependencies

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 must be placed in the webhooks folder of your light module.

Multiple webhook definitions

To make sure that two or more identical webhook definitions from different modules are always associated with their respective REST clients, Magnolia uses the light module name to create the REST client definitions.

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.

See also below Webhook parameters appended automatically.

If you use a pre-configured REST client (referenced through restClientName) instead of the url parameter in a webhook definition, the queryParameters property is not passed to the REST client.

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.

Webhook parameters appended automatically

Every parameter configured using the queryParameters property is sent in a webhook request.

However, no matter what queryParameters you have configured (if any), Magnolia always sends the following parameters:

With values taken from published/unpublished content

nodeType
path
recursive
workspace

With values supplied by the system

eventDate
eventId

Example configuration

If the following webhookConfig_1 webhook definition is available in two different light modules, example-light-module and whlm, then Magnolia sets the name property for their REST client definitions as webhook-example-light-module:webhookConfig_1 and webhook-whlm:webhookConfig_1, respectively.

webhookConfig_1.yaml

name: webhook1
url: https://httpdump.io/yxlbo
method: get
enabled: true

events:
  - name: goLive
    eventType: Published
  - name: outdated
    eventType: Unpublished
    filter: "@path LIKE '%out-of-date%'"

example-light-module
whlm

Webhook definition in the example-light-module module

Webhook definition in the whlm module

More examples

/example-light-module/webhooks/webhookConfig_1.yaml

name: webhook1 (1)
url: https://my.server.com/webhookEndpoint
method: GET
queryParameters:
  access_token: '2cf09447'
headers:
  "Content-Type": "application/json"
  "X_Custom_Header": "value"
enabled: true

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

1	The first half of this configuration defines the webhook name (`webhook1`) and the REST client properties.
2	The second half specifies the webhook events. Two webhook events are configured there:
3	`contentPublished` - to call the API whenever you publish a page.
4	`contentUnpublished` - to call the API whenever you unpublish a page, with a filter restriction applying though.

When you add this configuration to your light module, Magnolia will create the associated REST client automatically. You can check the full client configuration in the Definitions app.

Webhook definition in the example-light-module module

Usage

For usage, see the How to create a webhook page.

Webhooks module

Installing with Maven

Configuration

Properties

Webhook parameters appended automatically

With values taken from published/unpublished content

With values supplied by the system

Example configuration

More examples

Usage

Location

Main doc sections