Webhooks module

Edition DX Core

License

MLA

Issues

MGNLHOOK

Maven site

Webhooks

Latest

1.0.1

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>1.0.1</version>
</dependency>
<dependency>
  <groupId>info.magnolia.webhooks</groupId>
  <artifactId>magnolia-webhooks-events-jcr</artifactId>
  <version>1.0.1</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>

Webhooks configuration

All webhook definition yaml files should be placed in the webhooks folder of your light module.

Example

/light-modules/LIGHT_MODULE/webhooks/webhook-config.yaml

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.

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

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.

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

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

Feedback