Custom XP Pipelines and Processors in a Headless World: Where Your Code Goes in SitecoreAI

In Sitecore XP, pipelines and processors were the default way to extend the platform. A processor could resolve a URL, change rendered markup, react to a save or adjust publishing, all inside the same .NET process that served the site.

SitecoreAI removes the server role where most of that code ran. There is no Content Delivery role, Experience Edge serves a snapshot of content captured at publish time, and the front end is a separate headless application. Custom code still has a home, but the home depends on when the code needs to run: at request time, at publish time, or when content changes.

This post gives a method for classifying existing pipeline code and finding where each piece belongs. Platform behaviour is taken from the official SitecoreAI documentation and the Sitecore Accelerate cookbook referenced at the end; the author’s recommendations are labelled as such.

1. Where code runs in SitecoreAI

LocationRoleWhen it runsCustom code
Content management (CM) instanceAuthoring, workflow, publishing to Experience EdgeAuthoring and publish timePossible through the source-controlled platform project; several patterns are discouraged (section 6)
Experience EdgeServes published content through GraphQLRequest timeNo custom code; configuration and webhooks are managed through the Edge Admin API
Head applicationRouting, rendering, request handlingRequest timeYour application code, for example a Next.js app on the Content SDK
External servicesIntegrations, scheduled work, webhook receiversWhen triggeredYour services, called by webhooks or calling SitecoreAI APIs

Two platform facts drive most decisions:

  • There is no Content Delivery role. XP processors that ran on CD servers at request time have no SitecoreAI equivalent on the platform side.
  • Experience Edge publishes a static snapshot of Layout Service output for each item at publish time. Output that varies by user or query string is not supported.

The consequence: logic that must react to the visitor belongs in the head application. Logic that shapes published content runs at publish time on the CM. Logic that reacts to content changes belongs in external services triggered by webhooks.

Sources: Limitations and restrictions (SitecoreAI), Limitations and restrictions of Experience Edge, Admin REST API, The SitecoreAI build configuration.

2. Classifying XP pipelines and processors

For each processor, ask one question first: when does it need to run? The answer usually decides its new home.

XP extensionTypical examplesRuns atSitecoreAI homeBasis
Request pipeline processorshttpRequestBegin: redirects, URL and site resolutionRequest timeHead applicationDocumented
Rendering pipeline processorsmvc.renderRendering, renderField: markup changesRequest timeHead application componentsDocumented
Layout Service extensions, content resolversExtra data added to layout outputPublish timeCM if output is static; otherwise a GraphQL query from the componentDocumented
Item event handlersitem:saved, item:deletedContent changeWebhook event handler and an external serviceDocumented
Publishing processors and handlerspublish:end notificationsPublish timeWebhook on publish events, or an Experience Edge webhookDocumented; choice is a recommendation
Workflow actionsNotifications, external approvalsWorkflow transitionWebhook submit or validation actionDocumented
Scheduled agents and tasksImports, clean-up jobsScheduleExternal scheduler calling SitecoreAI APIsRecommendation
Editing UI customizationsCustom commands, ribbon buttons, field typesAuthoring timeMarketplace app, or removeDocumented; Marketplace is a recommendation
Search index customizationsComputed fields, custom indexesIndexingExternal search service fed by webhooksDocumented; replacement is a recommendation
Configuration-only changesSettings overridesStartupPatch file in the platform projectDocumented

Documented means the constraint or mechanism is stated in the Sitecore documentation or the Accelerate cookbook. Recommendation marks the author’s suggestion where the documentation does not prescribe a replacement.

Many processors exist only to support MVC rendering or the CD role. Those disappear with the move to headless and need no replacement. Identify them first, because they shrink the inventory.

Sources: Limitations and restrictions (SitecoreAI), Limitations and restrictions of Experience Edge, Webhooks, Transition from XM/XP to SitecoreAI (Accelerate), Use a patch file to customize the Sitecore configuration.

3. Request-time logic: the head application

In XP, httpRequestBegin and rendering processors could inspect the request and change the response before the page reached the visitor. In SitecoreAI, the request never reaches the CM. The head application receives it, fetches published content from Experience Edge, and renders the response.

Anything that depends on the visitor, the URL, cookies or headers therefore moves to the head application:

  • Request interception such as redirects, rewrites and locale detection: handled by the framework’s request layer. In a Content SDK 2.0 Next.js app, this is proxy.ts, which replaces middleware.ts following the Next.js 16 upgrade.
  • Output changes that renderField or mvc.renderRendering processors made: implemented in the React components that render the fields.
  • Visitor-specific data: fetched by the head application at request time from the system that owns it, such as a CRM or commerce API, because Edge output cannot vary by user or query string.

Two constraints to design for:

  • Edge rate limits apply to uncached requests, at 80 per second on the Delivery API. Cache Edge responses in the head application instead of querying Edge on every request.
  • Personalization is not a request processor. XP personalization rules do not carry over; SitecoreAI provides page and component variants configured in the Page builder.

Sources: Limitations and restrictions of Experience Edge, Content SDK v2.0 changelog, Transition from XM/XP to SitecoreAI (Accelerate).

4. Layout Service extensions and content resolvers

Code that extends Layout Service output, including content resolvers, still runs on the CM, but at publish time, not request time. Experience Edge stores the output as a static snapshot when the item is published. That changes how the code behaves:

ChangeEffect on Edge
Rendering configuration or a Layout Service extension changesAffected items must be republished
A content resolver queries a datasource or its children, and that content changesThe datasource, its children and every page or partial design that uses it may need republishing
A clone source or standard value changesDependent items must be republished
Language fallback configuration changesAffected items must be republished; fallback can be set only per instance

Guidance:

  • Keep resolver output static. A resolver that reads the current user, query string or time produces a value frozen at publish time, because Edge does not support contextual output.
  • Use integrated GraphQL for shared components. The Edge documentation recommends it to avoid double republishing when components share data.
  • Move frequently changing data out of resolvers. If data changes more often than pages are republished, the component should query it directly. This is the author’s recommendation, derived from the republishing rules above.

The Accelerate cookbook lists custom content resolvers among the patterns to move away from. They still work, but they slow future migration.

Sources: Limitations and restrictions of Experience Edge, Transition from XM/XP to SitecoreAI (Accelerate).

5. Event and workflow logic: webhooks

The SitecoreAI documentation is explicit: webhooks are the supported mechanism for reacting to system events. Instead of a handler running inside the platform, an external service subscribes to events and receives an HTTP request.

XP codeSitecoreAI replacement
Handler on item:added, item:saved, item:deleted and other item eventsWebhook event handler
Handler on publish:begin, publish:end, publish:failWebhook event handler on publish events
Code that must run after content reaches Experience EdgeExperience Edge webhook (OnEnd or OnUpdate)
Custom workflow action that notifiesWebhook submit action
Custom workflow action that blocks a transitionWebhook validation action

Behaviour that differs from an in-process handler:

  • No shared transaction. The handler no longer runs in the same process as the save, so it cannot cancel or modify the operation. Only a validation action can block a workflow transition. This point is the author’s inference from the webhook model.
  • Time limits. The default maximum time to send all webhooks for one request is 10 seconds; validation actions default to 3,000 ms.
  • No retries. If the endpoint returns an error, SitecoreAI does not resend the request; the error is logged.
  • Not for business logic inside SitecoreAI. The documentation states webhooks are not designed for that purpose; the logic belongs in the external service.

Sources: Webhooks, Webhook event handler configuration fields, Webhook validation action HTTP response, The webhook execution modes.

6. Code that stays on the CM

Customizing the CM is still possible, through documented, source-controlled mechanisms:

MechanismHow it works
Configuration patch filesPlace .config patch files in authoring/platform/App_Config/Include/ (Custom layer) for environment-independent settings, or authoring/platform/App_Config/Environment/ (Environment layer) for environment-specific settings. SitecoreAI merges them with Sitecore.config at runtime
Platform projectxmcloud.build.json defines buildTargets, such as Platform.csproj. The SitecoreAI build server builds the solution and deploys the artifacts to the CM instance
Web.config transformsMap an .xdt file to /web.config in the transforms section of xmcloud.build.json

What is not possible: Installing DLLs, configs or handlers through packages, as the XP Package Designer allowed. SitecoreAI environments are immutable, so every change goes through source control and a deployment.

What is discouraged: The Accelerate cookbook lists custom content resolvers, custom event handlers and customizations to the editing UI as patterns to move away from. They still work but slow future migration. Its content audit guidance also describes deploying custom C# code to the CM, for example to create custom bucket structures, as not a recommended practice.

Recommended approach (author’s recommendation):

  1. Prefer configuration patches over compiled code.
  2. Keep compiled CM code limited to logic that has no supported alternative.
  3. Document each remaining customization with the reason it must stay on the CM, so it can be revisited as platform capabilities change.

Sources: Use a patch file to customize the Sitecore configuration, Configuration layers, The SitecoreAI build configuration, Configure your environment, Migrating content between SitecoreAI environments, Transition from XM/XP to SitecoreAI (Accelerate), Content audit (Accelerate).

By classifying each pipeline and processor by when it needs to run, teams can find the right home for their custom code in SitecoreAI, whether that is the head application, a webhook or the CM, and leave behind the code the headless architecture no longer needs.

References

Leave a Reply