When working with workflows in Sitecore, clients often request automated notifications to keep track of important state changes. The most common requirement is email alerts.
Sitecore XM Cloud doesn't include out-of-the-box email notifications for workflow state changes. Since XM Cloud discourages server-side customizations, we need a cloud-native solution.
Webhook Submit Actions allow you to trigger HTTP calls when workflow actions occur—without writing server-side code. Here's how to set up email notifications when an item reaches the Approved state.
Navigate to your workflow:
/Sitecore/System/Workflows in the Content EditorInsert a Webhook Submit Action:
Configure the Webhook:
If your API requires auth, create an Authorization Item under:
/sitecore/System/Settings/Webhooks/Authorizations
Supported auth types:
ApiKeyBasicDigestWhen the workflow triggers, Sitecore sends a JSON payload like this:
1{
2 "ActionID": "d6588964-7c88-4650-a2bf-27dff4297d65",
3 "ActionName": "Approval",
4 "Comments": [{"Key": "Comments", "Value": "Looks perfect!"}],
5 "DataItem": {
6 "Id": "2e97a681-05ed-4a1c-92b0-87343b1d0e27",
7 "Name": "Home",
8 "TemplateId": "c6a5d6a9-85a0-4acc-8337-074270364850"
9 },
10 "PreviousState": {
11 "DisplayName": "Draft",
12 "StateID": "{A0E3A221-B774-4473-B623-1312FB5645CE}"
13 },
14 "UserName": "sitecore\admin",
15 "WorkflowName": "Approval Workflow"
16}Deploy this Next.js API to handle the webhook and send emails:
1// pages/api/workflow/notify.ts
2import sgMail from '@sendgrid/mail';
3import type { NextApiRequest, NextApiResponse } from 'next';
4
5// Initialize SendGrid
6sgMail.setApiKey(process.env.SENDGRID_API_KEY as string);
7
8interface WorkflowPayload {
9 ActionID: string;
10 ActionName: string;
11 Comments: Array<{
12 Key: string;
13 Value: string;
14 }>;
15 DataItem: {
16 Id: string;
17 Name: string;
18 TemplateId: string;
19 };
20 UserName: string;
21 WorkflowName: string;
22 PreviousState: {
23 DisplayName: string;
24 StateID: string;
25 };
26}
27
28export default async function handler(req: NextApiRequest, res: NextApiResponse) {
29 if (req.method !== 'POST') {
30 return res.status(405).json({ message: 'Method not allowed' });
31 }
32
33 try {
34 const payload: WorkflowPayload = req.body;
35
36 if (!payload.DataItem || !payload.UserName) {
37 return res.status(400).json({ error: 'Invalid payload format' });
38 }
39
40 const msg = {
41 to: process.env.NOTIFICATION_RECIPIENT || 'admin@yourdomain.com',
42 from: process.env.SENDER_EMAIL || 'noreply@yourdomain.com',
43 subject: 'Workflow Update: ' + payload.DataItem.Name + ' Approved',
44 html:
45 '<h2>Workflow Item Approved</h2>' +
46 '<p><strong>Content Item:</strong> ' + payload.DataItem.Name + '</p>' +
47 '<p><strong>ID:</strong> ' + payload.DataItem.Id + '</p>' +
48 '<p><strong>Approved By:</strong> ' + payload.UserName + '</p>' +
49 '<p><strong>Workflow:</strong> ' + payload.WorkflowName + '</p>' +
50 '<p><strong>Previous State:</strong> ' + (payload.PreviousState?.DisplayName || 'N/A') + '</p>' +
51 '<p><strong>Comments:</strong> ' + (payload.Comments?.[0]?.Value || 'No comments provided') + '</p>' +
52 '<p>Please review the item in <a href="' + process.env.SITECORE_APP_URL + '">Sitecore</a>.</p>',
53 };
54
55 await sgMail.send(msg);
56
57 return res.status(200).json({
58 success: true,
59 message: 'Notification sent successfully',
60 });
61 } catch (error) {
62 console.error('Error processing workflow notification:', error);
63 return res.status(500).json({
64 error: 'Failed to process notification',
65 details: error instanceof Error ? error.message : 'Unknown error',
66 });
67 }
68}
69By combining Webhook Submit Actions with a lightweight API, you can implement workflow emails in XM Cloud while adhering to best practices. Extend this further with:
Pro Tip: Test your webhook with tools like webhook.site before connecting to email services.
In this blog post, we will explore a common requirement in Sitecore Headless SXA, exposing site-specific settings and global data to the front end when working with a JSS headless site. ## Problem S
Read MoreRecently, while working with a Sitecore 10.4 deployment in an Azure environment, we encountered an interesting challenge: handling Sitecore Content Management (CM) and IdentityServer (SI) behind a pr
Read MoreIn this blog post, I'll walk you through the process of smoothly leveraging the Search SDK Starter Kit into a Sitecore Next.js solution. ## Prerequisites Before proceeding, ensure the following prer
Read More
![Leveraging Sitecore Search SDK Starter Kit into Your Sitecore Next.js Solution [Part 2]](/_next/image?url=%2Fimages%2Fpost%2Fstarter-kit.png&w=828&q=75)