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 the UNPUBLISH 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'"