Documentation

https://docs.magnolia-cms.com/product-docs/6.2/Features/Webhooks.html

https://docs.magnolia-cms.com/product-docs/6.2/Modules/List-of-modules/REST-Client-module.html

Summary - Proposal

In webhook definition - Fix confusion with "queryParameters"

queryParameters property in Webhook behaviour is confusing. And not aligned with documentation. But we dont want to change queryParameters behaviour as it would break customer projects.

Plan:

• Document current unexpected behaviour of queryParameters.
  • In a webhook definition:
    1. The queryParameters  are always sent as a query string, regardless of whether GET or POST method is used. When using POST, only the rest of the values are sent in the body.
    2. When the Webhook specifies an existing REST Client: The queryParameters  specified in the webhook definition are not passed to an existing restClient at all. The rest of the parameters (workspace, path, ...) are always sent as query string, regardless of whether we use POST or GET.
• Deprecate "queryParameters" property
• Introduce new "parameters" property.
  • Only used when webhook defines a url. (Not used when webhook uses existing REST Client)
  • Included in querystring when using GET.
  • Included in body when using POST.

In Webhook YAML definition - Developer will be able add things to the context object.

• Add a context  property to the webhook YAML definition, so that developer can add items to the context object.
• They can then add properties to it via a map. Like:
  
  • context
    • catalog: myCatalog
    • butter: yummy brand
• This new context  property will only used when the webhook defines an existing RestClient/RestCall to use.
• Note: The webhook already has a "context", but developer can not add anything to it now.
  • (it is those same properties automatically added to querystring or body.)
• This context object is already passed to the RestCall and can be used in defaultValues there.
  • (Like this: "{context.butter}".)
• (Note: This is similar to what developers could do in the webhook incubator.)
  

REST Client context from Webhook will include content node.

• The webhook supplies the content node to the RestClient. (If it makes sense for the type of event. It does make sense for "publish" "unpublish" events.)
• It is available at context.content  in the RestClient, for example for usage in "defaultValues".
• (Note: However the full content node is not auto-added to the querystring or body. But developer could add it to body if they want.)

Webhook body will include "uuid"

• uuid of content item is added to the "context" and is added to this list of "auto added parameters". (If it makes sense for the type of event. It does make sense for "publish" "unpublish" events.)
  
  • https://docs.magnolia-cms.com/webhooks/1.0/index.html#auto-added-params

Note: Here are the current default properties: (These are available already in REST Client defaultValues - with prefix "context". ie {context.path}

• from content:
  • nodeType
  • path
  • recursive
  • workspace
• from system:
  • eventDate
  • eventId

Java for dynamic custom content or body in Rest Client

• Java can be used to populate the context object in the RestClient / RestCall
• Java can be used to create a custom body in the RestClient / RestCall (e.g. BodyWriter)

We considered adding flexibility to use Java in the Webhook. But we prefer to add this to the RestClient - as our general architectural intent is that the webhooks are light and when something needs more custom behaviour - this is to be done in the RESTClient.