Webhooks
Webhooks in general
What is a webhook?
A webhook is a user-defined callback, triggered by some event (content change or a code push to a repository), which makes a REST call to an external API, usually a build pipeline. The build system then creates a new build that incorporates the changed content.
Common use cases
-
Triggering a build
The most common use for webhooks in a CMS is to trigger building a static site (Jamstack) whenever content is changed.
-
Updating search indexes
You can configure a webhook to trigger a specific search service. Upon executing a webhook, the service will perform a re-indexing of content.
-
Sending notifications
A webhook can be configured to send a request to a messaging service in order to send notifications to staff members or site users.
-
Synchronizing content
Last but not least, a webhook can be configured to send a request to a third-party service to orchestrate moving or updating content on a CDN or database.
Support for webhooks in Magnolia
Magnolia Webhooks is a DX Core feature and has been available since the 6.2.22 Magnolia release. In the Magnolia implementation, webhooks are:
-
Configured in Yaml files.
-
Registered in a webhook registry.
-
Triggered by the
PUBLISH
or theUNPUBLISH
event(s). -
Configured for event definitions that are based on Magnolia Content Types.
-
Queued for asynchronous processing to avoid the interruption of the main UI thread.
-
Filterable by:
-
Path
-
Repository
-
Node Type
-
AND/OR filter operations
-
Recursion
-
Webhook REST configuration parameters
Webhook REST requests can be configured using the following parameters:
-
URL
-
REST method
-
Query parameters
-
Headers
-
List of webhook events
Webhook REST request configuration options
There are two ways you can configure a webhook REST request.
-
Provide REST request properties together with webhook event definition properties in one Yaml file. In this case, a new REST client is created automatically:
name: webhook1 url: https://my.server.com/webhookEndpoint method: POST queryParameters: access_token: '2cf09447' headers: "Content-Type": "application/json" "X_Custom_Header": "value" enabled: true events: - name: contentPublished eventType: Published entity: Content filter: "@path LIKE '%whatever%' or @nodeType = 'mgnl:page'" - name: contentUnpublished eventType: Unpublished entity: Content filter: "@path LIKE '%whatever%' or @nodeType = 'mgnl:page'"
-
To avoid redundant configuration, you can use (reference) an existing REST client definition, as shown in the following example configuration:
name: webhook1 restClientName: existingCreatedRestClient restCallName: triggerBuild enabled: true events: - name: contentPublished eventType: Published entity: Content filter: "@path LIKE '%whatever%' or @nodeType = 'mgnl:page'" - name: contentUnpublished eventType: Unpublished entity: Content filter: "@path LIKE '%whatever%' or @nodeType = 'mgnl:page'"