Sitecore Webhooks in action

Sitecore introduced webhooks in Sitecore 10.3 release. The webhooks allows you to get real-time notifications on Sitecore server-side events to other systems.

What are webhooks?

Webhooks are basically HTTP call-backs. These are automated messages used for communication between two systems when an event is triggered on one system and the other system needs to be notified of the event. The webhooks payload usually consists of a lightweight message about the event in JSON or XML format.

What is the need for webhooks in Sitecore?

This is one of the features first introduced in Sitecore XM Cloud and later incorporated into Sitecore XP release. In a composable DXP with a SaaS based CMS like XM Cloud, we need an easy way to communicate with external systems using a plug and play framework like webhooks. This allows the CMS to notify the external systems of the server-side events happening at Sitecore so that the systems can take necessary actions of their own. An example of this is to clear edge caching on a publish event.

With Sitecore XP, the webhooks can be used for triggering notifications on updates to critical content, on workflow submissions and even to perform external validations on a workflow action.

Types of webhooks available in Sitecore XP

There are three types of webhooks available in Sitecore XP.

Webhook event handler

This webhook is fired on supported events such as item:added, item:deleted etc. This can be used for notifying other systems about changes happened to important content on your website, for e.g. legal documents. The full list of supported events can be found in the Sitecore webhooks documentation. The payload of this event contains the details of the item being modified, including the list of field level changes for events like item:saved event.

Webhook submit action

This type of webhook is used for notifying other systems about workflow state change events. The payload for this webhook request contains the information about the item in the workflow and the details of the workflow itself including the current and next state.

Webhook validation action

This webhook is used for performing external validation of the item in workflow, on workflow state change or action execution. Unlike the above two webhooks Sitecore expects a valid response for this webhook request. The external webhook endpoint should provide a response with Webhook validation HTTP response payload message which contains a flag indicating whether the validation was successful and a message field for validation error message. If the external validation is failed or a if a response is not received in expected time the item's workflow state won't change.

How to configure webhooks in Sitecore XP?

Webhook event handler

The webhook event handlers are created under /sitecore/system/Webhooks in the content tree.

On the Webhook Event Handler item you have the option to configure the following field values

• Description: A short description of the purpose of the webhook event handler
• Events: The list of item events the handler should be triggered on. The full list of supported events are as follows

Source: Webhook event handler configuration fields (sitecore.com)

• Rule: Specify any rules applied to the event handler so that it only gets triggered when the specific conditions are met.
• Enabled: Enable/Disable the event handler.
• Url: Url of the webhook receiver endpoint.
• Authorization: Optional authorization information for the webhook receiver endpoint used for authentication. The authorization items must be created under /sitecore/system/Settings/Webhooks/Authorizations node in the content tree. The supported Authorization types are
• ApiKey
• Basic
• Digest
• OAuth2ClientCredentialsGrant
• OAuth2PasswordCredentialsGrant
• Serialization Type: The output payload serialization format. The supported formats are
• JSON
• XML

Webhook submit action

The webhook submit action items can be created under any of the workflow state or action item as shown below.

The webhook submit action has the same fields as webhook event handler item except the Rules field.

Webhook Validation action

The webhook validation action items can be created under any of the workflow action items as shown below.

The webhook validation action has the same fields as webhook submit action.

Sitecore Webhooks in action

There are many use cases for the webhooks, and they really depend on your project specific business requirements. For this demo, I picked a couple of my own requirements below.

1. Get Slack and Email notification on specific item events.
2. Get Slack and Email notification when an item is submitted for approval.
3. Do a third-party validation on item approval and reject the item if the validation fails.

To get the Slack notifications, we need a URL to post messages to Slack. For this demo, I created a Slack Incoming Webhooks app in my Slack workspace using this guide which gave an endpoint I could use to post messages to a Slack channel I configured while setting up the incoming webhooks app.

For Email notifications I used the free tier Mailjet subscription and setup my api keys following their developer documentation. You can use any of the email services or your own SMTP server for this.

Slack and the Email service I used needs the messages sent in a specific format which is different to what Sitecore sends, so I needed a middleware to transform the messages to Slack and Email service supported formats. For this, I created a web api with a controller called WebhooksController the following actions and hosted on a container.

• LogItemEvent: Endpoint to receive the webhook event handler notifications. Transforms the payload and pushed messages to Slack and Email.
• WokflowSubmit: Endpoint to receive the webhook submit action notifications. Transforms the payload and pushed messages to Slack and Email.
• ValidateWokflowState: Endpoint for third party validation of the item in workflow state. For the validation for this demo purpose, I am just checking if the item is submitted for approval during even minute of the hour, if not failing the validation.

You can use your own preferred ways to host this middleware logic including Azure functions or AWS Lambda. You can find the sample payload JSON of different webhook events from the Sitecore documentation. Or you could configure your webhooks to send notifications to online webhook test site like webhooks.site to capture the JSON and create your model classes. Once I had my webservice endpoints ready I configured the following webhooks in Sitecore.

Item Event Handler

Webhook Submit Action

Webhook Validation Action

You can find the full source code of the webservice project on my github repo. Once everything is configured as above you will start receiving Slack and Email notifications as below.

Although this blog turned out to be a little longer than I anticipated, I wanted to cover both theory and the practical usage of the Sitecore webhooks. Hope this helps. Happy Sitecoring!