Webhooks & GraphQL: New Sitecore XP Communication Options
One moment that sticks in my mind from last year's SUGCON, was when Roger Connolly, Sitecore's VP of Product Management, talked about all the new service-oriented features coming to Experience Manager (XM) Cloud like GraphQL management and webhook support, and he noted in passing that these features would also be coming (with the just released version 10.3) to Sitecore's non-cloud Experience Platform (XP) and XM products. There was a pause, and then a loud burst of applause from the Sitecore professionals gathered in Budapest.
Why were we so excited? Well, it's one thing to hear about completely different development paradigms being offered in a new cloud product, but it's quite another to realize they might be just an upgrade away from the sites you work with every day. We were excited to get our hands on these tools and use them in our day-to-day work.
These changes are important because a shift is happening in how development gets done with Sitecore. The old paradigm was to build highly complex, bespoke functionality. "Can you do this in Sitecore? Yes!" as the old Symposium tagline went. Just about every piece of Sitecore functionality could be customized. As Sitecore developers, we took great pride in plunging into Sitecore configuration to find just the right pipeline or event handler for the job. But this ability to tweak and change the platform comes at a cost. Solutions become harder to maintain and upgrade. The Lego bricks are harder to take apart.
This new paradigm is different. Rather than build the customizations with dozens or hundreds of lines of C# code, you set them up in screens, and simply point one system to another. When an event happens on Sitecore, like an item being saved, use a webhook to send out a call to an integration platform like Sitecore Connect, which then can pass that information on to other systems that support open APIs, such as OrderCloud, Sitecore Digital Asset Management (DAM), or an AI platform. Then, those external systems can make required calls back to Sitecore using GraphQL, either directly or via an integration platform. You can still do anything with Sitecore, but now you can do a lot more without writing code.
A Look at Webhooks in Sitecore
For Sitecore developers, a good analogy for webhooks is that they’re remote events on steroids. Just as regular Sitecore events allow custom functionality to be triggered when an item is saved, remote events allow code to be executed on a separate machine. This is the mechanism Sitecore uses to ensure that when an item is published from the master to the web database on a Content Management server, the cached values for that item are cleared on all the Content Delivery servers. With webhooks, these events can be broadcast to third-party services and integration platforms, like Sitecore Connect or Zapier. So now when an item is updated or enters a workflow state, an AI service can be notified to generate an image, a translation service to generate content, or internal systems can initiate a legal review process or marketing coordination. Basically, instead of bringing those systems and roles into Sitecore, Sitecore can broadcast its changes.
If you go to the Sitecore 10.3 content tree, you will see a new item /Sitecore/System/Webhooks:
The process of setting up a webhook here is quite simple. Add a child to the webhook root; then specify the events ("item saved", "item added", etc.) that will trigger the webhook, and a URL to post to. Optionally, you can configure authorization if the downstream system requires it and use the rules engine to restrict the items that trigger the webhook.
But how do you test this out? One option is to use an integration tool with a free developer tier. I had a good experience working with Pipedream, which has a helpful developer experience and offers a free pricing tier. Creating a webhook URL can be done in a few seconds, and when you activate the webhook in Sitecore, you will immediately see events come through.
We can see the details sent by Sitecore by clicking on the new event:
We can build out downstream functionality by clicking on the [+] icon, which allows you to create integrations using Node.js or Python or use off-the-shelf integrations with Google Sheets or Slack. The UI is appealing, and if you prefer developing in C#, Azure Functions is a logical option. Whichever tool you use, enabling Sitecore events to trigger behaviors isn't difficult. You have access to the Sitecore item values, so you can pass them to integrate any system with open REST APIs.
There's a parallel mechanism for Workflows, with two new workflow item types, a non-blocking update event that can notify another system when a workflow action is submitted, and a blocking validation event that can delegate validation to an external system.
These are illustrated with a new "Sample Webhook Workflow":
The validation action could allow integration with a centralized content governance system or perform any other kind of validation that can be done in an immediate, not blocking manner. For integrations that involve a review process outside of Sitecore, one could imagine an item going into a pending state, a system being notified by a Webhook Submit Action, and then after say a legal review, the intermediate system sending back a command to Sitecore to advance the item, using 10.3's GraphQL capabilities discussed below.
An Extended GraphQL Endpoint
GraphQL has been part of the Sitecore developer's toolkit since JSS was introduced, to query item data from a Sitecore CD or Experience Edge. Setting this up required JSS to be installed, and the GraphQL endpoint had to be manually configured. With 10.3, GraphQL becomes a native part of the platform, can be enabled with a single configuration flag, and supports a much wider range of functionality, such as updating users and groups, initiating publishing, inspecting and terminating jobs, rebuilding indexes, and updating passwords. Much of the administrative functions that require access to the Sitecore Control Panel can now be managed by external systems.
This screenshot from Sitecore's GraphQL IDE shows both the range of administrative actions currently supported and the auto-complete style discovery that GraphQL tooling offers.
A key feature of GraphQL, and its major advantage over traditional REST APIs, is that the client can shape the data it gets back. In the following screenshot, you can see on the left they use a query syntax that looks a lot like JSON (with the colons, commas, and values removed), and on the right, you get just the data you requested, at the level of depth you need.
The ability to shape the request has two big advantages:
- Communication can be less chatty. For example, to get a root item, and two levels of descendants, you can specify that structure in the query, rather than making two get children calls, and additional calls to get the required details on each item.
- Features can be added without breaking existing client code since if a new field or object type is not requested, it won't appear, even if it was introduced after the consuming code was written. Sitecore versions their endpoint "V1", but per GraphQL best practices documentation, it's not necessary.
A New Way of Building Integrations
With these two tools, it’s possible to build sophisticated integrations with external systems without writing a line of Sitecore code. The less code written, the easier upgrades are, and the easier it is to migrate to XM Cloud. It is gratifying to see these service-first development techniques available to the full CMS product line and shows that the "Classic" XP and XM products will benefit from the research and development being done for the new flagship XM Cloud product.
Dig Deeper into GraphQL and Webhooks
- GraphQL's interactive getting-started tutorial.
- Fellow MVP Jeremy Davis's deep dive.
- A guide to Webhook testing.
- Sitecore's documentation on 10.3's GraphQL and Webhook support.
- A recent personal blog post on using Postman to authenticate GraphQL sessions.
If you'd like to see more on these features and are in the Boston area, please come to the March 1 Sitecore User Group at Velir, where we'll walk through building out some live integrations.