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.

  1. 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'"

  2. 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'"
Related topics
Feedback