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 handler | Submit action | Validation action | Experience Edge webhook | |
|---|---|---|---|---|
| Layer | CM | CM workflow | CM workflow | Experience Edge |
| Configured in | Content tree | Workflow | Workflow | Edge Admin REST API |
| Trigger | Item and publish events | Workflow state change or command | Workflow state change or command | Edge publishing job |
| Blocks the action | No | No | Yes: the endpoint approves or rejects | No |
| Timeout | 10 seconds for all webhooks in a request | 10 seconds for all webhooks in a request | 3,000 ms default, 10,000 ms maximum | 30 seconds |
| On failure | Not resent; error logged | Not resent; error logged | Item stays in its current state | Disabled 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:
| Field | Purpose |
|---|---|
| Enabled | Turns the webhook on or off |
| Events | The events that send requests; none selected means no requests |
| Rule | Limits which items trigger requests; no rule means every item does |
| Url | The receiving endpoint; use HTTPS |
| Serialization Type | JSON (default) or XML; XML uses event as the root element |
| Authorization | An 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
| Property | Type | Effect |
|---|---|---|
| IsValid | Boolean | true lets the item move to the next state; false blocks it |
| Message | String | Optional; 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:
| Mode | Fires | Body |
|---|---|---|
| OnEnd (default) | Once, at the end of the publishing job | The static body you define; set a content-type header to control its format |
| OnUpdate | With the entity changes that caused it | Always 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.
| Integration | Recommended mechanism | Reason |
|---|---|---|
| Revalidate the head application’s cache or rebuild a static site | Edge webhook, OnEnd | Runs once, after Edge has finished the publishing job |
| Update an external search index from published content | Edge webhook, OnUpdate | Sends the changed entities, so only those need re-indexing |
| Notify a team or ticketing system when content is approved | Workflow submit action | Fires on the workflow transition itself |
| Block approval until an external compliance check passes | Workflow validation action | The only mechanism that can stop a transition |
| Sync new items of a given template to a downstream system | Event handler on item:added with a template rule | Fires in the CM, scoped by the rule |
| Alert on failed publishing | Event handler on publish:fail | Reports 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 constraint | Design response |
|---|---|
| 10-second budget for all CM webhooks in a request; 30 seconds for Edge | Acknowledge immediately and process the work asynchronously, for example through a queue |
| 3,000 ms default for validation actions | Keep validation logic fast and synchronous; avoid long external calls |
| CM webhooks are not resent on error | Log every delivery and reconcile on a schedule for integrations that must not miss events |
| item:saved can fire several times per operation | Make processing idempotent, keyed on item ID, version and language |
| Edge disables a webhook after 10 consecutive failures | Monitor lastRuns and alert when disabled becomes true |
| Webhooks are not for business logic inside SitecoreAI | Keep 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
- Webhooks: webhook types, roles, timeout and retry behaviour
- Webhook event handler configuration fields: fields and supported events
- Webhook event handler HTTP request: payload properties
- Webhook validation action HTTP response: response format and timeout
- Walkthrough: Using an authorization item: securing CM webhooks
- Admin REST API: Edge webhook endpoints
- Create a JSON web token for Experience Edge APIs: authorizing Admin API requests
- Webhook objects: webhook properties and automatic deactivation
- The webhook execution modes: OnEnd and OnUpdate