Webhooks module
Edition |
DX Core |
License |
|
Issues |
|
Git |
Enterprise / webhooks |
Maven site |
|
Latest |
1.0.2 |
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.2</version>
</dependency>
<dependency>
<groupId>info.magnolia.webhooks</groupId>
<artifactId>magnolia-webhooks-events</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>info.magnolia.webhooks</groupId>
<artifactId>magnolia-webhooks-events-jcr</artifactId>
<version>1.0.2</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 must be placed in the webhooks
folder of your light module.
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 | ||
---|---|---|---|
|
required Name of the webhook. The name must be unique across all webhook definitions. |
||
|
required, if there is no associated REST client referenced through the The URL of the target endpoint that is notified when an event occurs. |
||
|
required, if no associated REST client is referenced. The HTTP method used when Magnolia connects to the target endpoint for an event. Supported methods: |
||
|
optional Key-value map with the parameters to be sent as:
|
||
|
optional Key-value map with the headers to be sent with an HTTP request. Example
|
||
|
required, if the Name of an already existing REST client configuration that will be used when a webhook event occurs. |
||
|
required, if the Name of an already existing REST client call that will be used when a webhook event occurs. |
||
|
required Boolean value which enables or disables the webhook. If |
||
|
required Node with a list of webhook events.
Example
|
||
|
required Name of a webhook event. The name must be unique across all event definitions in the same file. |
||
|
required Type of the webhook event. Two event type values are allowed at the moment,
|
||
|
optional Type of the content. The value can be either |
||
|
optional String that allows you to filter the events. Example
The filter grammar expressions are enclosed in parentheses and can be combined using Filter properties
Filter operators The The |
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.
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%'"
More examples
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. |
Usage
For usage, see the How to create a webhook page.