(Web)hooked on a feeling

Within Sitecore XM Cloud and Sitecore 10.3, there is a new webhook functionality that allows notifications to be sent in the form of an HTTP post to a configured URL about workflow events.

There are three types of webhooks:

• Webhook workflow submit action;
• Webhook workflow validation action, which is a special webhook that requires a response in the form of a JSON field indicating success or failure;
• Webhook event handler, which is based on Sitecore events such as item-save and publish-end. In this blog I will discuss this type of blog in more detail.

Webhooks based on an event can also be used for your own custom events, where you can determine which data the event contains. A Sitecore event has an Array of objects as a parameter. This allows you to pass all the necessary data to the webhook when the custom event is triggered.

Webhooks in Sitecore run only on the Content Management (CM) instance, and if they fail, there is no built-in retry functionality. However, using a third-party integration tool such as Sitecore Connect on Workato can provide retry functionality and greater visibility into webhook availability. Item events, such as item:save for media items, do not include binary data in webhooks, only the blob's guid. But webhooks can get very large. For example, the data of various rich text fields can be in the webhook. The theoretical maximum size of a Sitecore field is NVARCHAR(MAX) is 2 Gbytes.

Rule Engine

Only events with an item as the first parameter can use rules in a Sitecore webhook. If the first event parameter is not an item, the rule engine is not called.

Webhooks based on custom events

You can use all available events, or even create custom events for use with webhooks by adding the desired event to the "/sitecore/templates/System/Webhooks/Events Folder”. Raising a custom event can be done in code by calling Sitecore.Events.RaiseEvent with your custom event name and an object array.

Formatting Custom Event Object

If you compare a custom event webhooks with the exact same parameters as a Sitecore event, the custom event may have different naming in the JSON. Sitecore has internal logic built-in to format specific events. The formatting is internal in the Sitecore kernel and cannot be extended. 
However, Sitecore uses Newtonsoft.Json for their serialization, and you can use JSON formatting Serialization Attributes. Sitecore has been using Newtonsoft.Json for many years, but if Sitecore decides to switch to a different library in the future, this may break.

Send a webhook to Microsoft Teams

The simplest JSON webhook request to Teams is {‘text':'Hello World’}. A string JSON field is given the default name "String". For example, a Teams message requires the field 'text'. One way to achieve this is to use an external webhook relay service. Another way is to use Newtonsoft.Json and create a custom event, this will give you control over what data the webhook should contain and control over the naming with JSON formatting. To get a String JSON value with a specific name, you can create a JSON converter that presents an object as a string.

The GitHub repo has a demo code for creating events with desired data for Sitecore Webhooks.