Webhooks in SitecoreAI: Building Event-Driven Integrations

A Webhook in SitecoreAI allows Sitecore to integrate with external services and applications via event-driven integrations. Unlike pulling for updates, external services are notified via HTTP requests of changes or events that occur within Sitecore. Events may include updates to content or changes to workflow or publishing status.

With SitecoreAI, documented webhook mechanisms allow external services to subscribe to events and perform actions outside of the Sitecore platform.

Prior to SitecoreAI, custom event handlers and pipeline processors were used to respond to platform events in Sitecore XP implementations.

SitecoreAI provides four mechanisms of integration across two environments: three in Content Management (CM) and one in Experience Edge. These are Event Handler Webhooks in Sitecore, Workflow Submit and Workflow Validation Actions, and Experience Edge Webhooks. Each of these mechanisms is designed to integrate with external services to perform a specific action based on triggers and timeouts and behave in a certain way when failures occur.

The four webhook mechanisms at a glance

Event handlerSubmit actionValidation actionExperience Edge webhook
LayerCMCM workflowCM workflowExperience Edge
Configured inContent treeWorkflowWorkflowEdge Admin REST API
TriggerItem and publish eventsWorkflow state change or commandWorkflow state change or commandEdge publishing job
Blocks the actionNoNoYes: the endpoint approves or rejectsNo
Timeout10 seconds for all webhooks in a request10 seconds for all webhooks in a request3,000 ms default, 10,000 ms maximum30 seconds
On failureNot resent; error loggedNot resent; error loggedItem stays in its current stateDisabled after 10 consecutive failures

Creating or viewing CM webhooks requires the Developer or Admin role. Edge webhooks require an Edge administration client created in SitecoreAI Deploy.

Sources: Webhooks, Webhook validation action HTTP response, Webhook objects, Admin REST API.

1. Webhook event handlers

An event handler sends an HTTP POST to an external endpoint when a supported system event occurs. To create one, open /sitecore/System/Webhooks in the Content Editor, right-click Webhooks, and select Insert > Webhook Event Handler.

Configuration fields:

FieldPurpose
EnabledTurns the webhook on or off
EventsThe events that send requests; none selected means no requests
RuleLimits which items trigger requests; no rule means every item does
UrlThe receiving endpoint; use HTTPS
Serialization TypeJSON (default) or XML; XML uses event as the root element
AuthorizationAn authorization item, if the endpoint requires authentication

Supported events:

  • Item lifecycle: item:added, item:versionAdded, item:cloneAdded, item:copied, item:moved, item:renamed, item:deleting, item:deleted, item:versionRemoved
  • Item state: item:saved, item:locked, item:unlocked, item:sortorderchanged, item:templateChanged
  • Publishing: publish:begin, publish:end, publish:fail, publish:statusUpdated

Every payload recognises the event and the webhook in Sitecore, followed by event-specific properties, such as Item for item events or PublisherOptions for publish events.

An item:added payload captured from a SitecoreAI environment (trimmed):

{
  "EventName": "item:added",
  "Item": {
    "Language": "en",
    "Version": 1,
    "Id": "7e05f750-f5f4-47ce-94dc-b0f52ce1d96f",
    "Name": "Webhook Test",
    "ParentId": "6ba7a301-5eec-4efa-a6ce-5949b647b7e6",
    "TemplateId": "0437fee2-44c9-46a6-abe9-28858d9fee8c",
    "TemplateName": "Template Folder",
    "SharedFields": [],
    "UnversionedFields": [],
    "VersionedFields": [
      { "Id": "52807595-...", "Value": "sitecore\\<user>", "Version": 1, "Language": "en" }
    ]
  },
  "WebhookItemId": "<webhook item ID>",
  "WebhookItemName": "Test - item saved"
}
Copy

A publish:end payload from the same environment:

{
  "EventName": "publish:end",
  "PublisherOptions": {
    "CompareRevisions": true,
    "Deep": true,
    "Mode": "SingleItem",
    "PublishDate": "2026-11-17T06:37:45.812Z",
    "PublishingTargets": ["{8E080626-DDC3-4EF4-A1D1-F0BE4A200254}"],
    "RepublishAll": false,
    "SourceDatabaseName": "master",
    "TargetDatabaseName": "experienceedge",
    "RootItemId": "7d2fa73d-6ae7-47cb-8d0b-d64671768c82",
    "UserName": "sitecore\\<user>",
    "WillBeQueued": true,
    "Languages": ["en"]
  },
  "WebhookItemId": "<webhook item ID>",
  "WebhookItemName": "Test - item saved"
}
Copy

Observed in testing:

  • Creating an item sent both item:added and item:saved at the same time.
  • With no rule configured, publishing the webhook item itself triggered publish:end, guaranteeing that a webhook without a rule fire for every item.
  • The publish:end payload reports TargetDatabaseName: “experienceedge” and WillBeQueued: true. This shows that the CM hands up the work to a queue for Edge, instaed of reporting that content is already available on Edge. The documentation does not state this, but it is consistent with using Edge webhooks for integrations that read from Edge.

Three behaviours to design for:

  • Always define a rule. The documentation strongly recommends rules to avoid performance degradation from a large volume of requests.
  • item:saved can fire several times during a single UI operation. The receiver must tolerate duplicates.
  • Failed requests are not resent. If the endpoint returns an error, SitecoreAI logs it and moves on.

Sources: Walkthrough: Creating and configuring a webhook event handler, Webhook event handler configuration fields, Webhook event handler HTTP request, Webhooks.

2. Workflow webhooks: submit and validation actions

Workflow webhook in Sitecore run when an item changes workflow state or a workflow command executes. They come in two forms.

Submit action: a notification. It sends a request when, for example, an item enters the approved state. It does not affect the transition.

Validation action: a gate. A third-party service decides whether the transition goes ahead. The endpoint must return a response in this shape (JSON or XML):

{ "IsValid": true, "Message": "" }
Copy
{ "IsValid": false, "Message": "Error message will be seen on UI and logged." }
Copy
PropertyTypeEffect
IsValidBooleantrue lets the item move to the next state; false blocks it
MessageStringOptional; shown to the author and written to the log

The validation endpoint must respond quickly. The default wait is 3,000 ms, configurable up to 10,000 ms through the Sitecore.HttpClientTimeout setting in Sitecore.config. If the endpoint does not validate the command in time, the workflow action fails and the item stays in its current state.

Typical uses are external compliance or legal checks before approval, and notifying a team or ticketing system when content is approved.

Sources: Webhooks, Walkthrough: Adding and configuring a webhook submit action, Walkthrough: Adding and configuring a webhook validation action, Webhook validation action HTTP response.

3. Experience Edge webhooks

Edge webhooks are triggered by Experience Edge’s own publishing job, not by CM events. They are managed through the Edge Admin REST API at https://edge.sitecorecloud.io/api/admin/v1.

Authorization: create an Edge administration client for the environment in SitecoreAI Deploy to get a client ID and secret. Exchange them for a JSON Web Token (JWT), which expires after 24 hours, and send it as Authorization: Bearer <JWT>.

Create a webhook with POST /webhooks. The URI must use HTTPS; HTTP is not supported.

{
  "label": "Revalidate head application cache",
  "uri": "https://<your-endpoint>/hooks/edge",
  "method": "POST",
  "headers": {
    "x-webhook-key": "<shared secret>"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "<your name>",
  "executionMode": "OnEnd"
}
Copy

Execution modes:

ModeFiresBody
OnEnd (default)Once, at the end of the publishing jobThe static body you define; set a content-type header to control its format
OnUpdateWith the entity changes that caused itAlways application/json; add static data with bodyInclude, which must be valid JSON

Operational behaviour:

  • Automatic deactivation. A run fails if the endpoint does not respond within 30 seconds. After 10 consecutive failures, Edge sets disabled to true. Fix the cause, then send PUT /webhooks/{id} with disabled: false.
  • Edge runtime publishing triggers fewer webhooks, because it publishes fewer items than snapshot publishing.
  • Webhooks cannot be scoped by site. Edge uses one content scope per environment, so a webhook in Sitecore fires for every site in it.

Sources: Admin REST API, Create a JSON web token for Experience Edge APIs, Webhook objects, The webhook execution modes, Authorization and API access, Limitations and restrictions of Experience Edge.

4. Choosing the right webhook in Sitecore

The deciding question is: does the receiving system need content to be available on Experience Edge? If it reads from Edge, trigger it from Edge. If it only needs to know that something happened in the CM, a CM webhook is sufficient.

IntegrationRecommended mechanismReason
Revalidate the head application’s cache or rebuild a static siteEdge webhook, OnEndRuns once, after Edge has finished the publishing job
Update an external search index from published contentEdge webhook, OnUpdateSends the changed entities, so only those need re-indexing
Notify a team or ticketing system when content is approvedWorkflow submit actionFires on the workflow transition itself
Block approval until an external compliance check passesWorkflow validation actionThe only mechanism that can stop a transition
Sync new items of a given template to a downstream systemEvent handler on item:added with a template ruleFires in the CM, scoped by the rule
Alert on failed publishingEvent handler on publish:failReports CM publishing failures directly

This mapping is the author’s recommendation, derived from the documented trigger and payload of each mechanism. It is not an official Sitecore decision table.

5. Designing the receiving service

The documented limits shape the receiver more than any framework choice.

Documented constraintDesign response
10-second budget for all CM webhooks in a request; 30 seconds for EdgeAcknowledge immediately and process the work asynchronously, for example through a queue
3,000 ms default for validation actionsKeep validation logic fast and synchronous; avoid long external calls
CM webhooks are not resent on errorLog every delivery and reconcile on a schedule for integrations that must not miss events
item:saved can fire several times per operationMake processing idempotent, keyed on item ID, version and language
Edge disables a webhook after 10 consecutive failuresMonitor lastRuns and alert when disabled becomes true
Webhooks are not for business logic inside SitecoreAIKeep all logic in the external service

Securing the endpoint:

  • CM webhooks: assign an authorization item, created under /sitecore/System/Settings/Webhooks/Authorizations. SitecoreAI supports several authentication types, including OAuth 2.0 Client Credentials Grant.
  • Edge webhooks: send a shared credential in the webhook’s headers object and validate it in the receiver.
  • Both: use HTTPS, which Edge enforces and the CM documentation recommends.

The design responses above are standard integration practice applied to Sitecore’s documented limits. The constraints themselves come from the official documentation.

Sources: Webhooks, Walkthrough: Using an authorization item, Webhook objects, Webhook event handler configuration fields.

By matching each integration to the right mechanism, whether a CM event, a workflow transition or an Experience Edge publish, developers can build event-driven integrations that stay reliable, secure and easy to maintain as their SitecoreAI solution grows.

References

Leave a Reply