掌握 SitecoreAI 中的 Webhooks：完整企业集成蓝图（2026 版）

SitecoreAI 是 Sitecore 于 2025 年 Symposium 上发布的统一平台，作为 XM Cloud 的继任者，保留了让 XM Cloud 有别于传统 Sitecore XP/XM 的事件驱动集成模型。您仍然无法将自定义 .NET 管道处理器或事件处理器部署到托管内容管理层。相反，每一次有意义的创作操作（保存项目、工作流推进、表单提交、发布完成）都可以触发一个携带 JSON（或 XML）有效负载的出站 HTTP 请求，发送到平台外部的任意位置：Azure Functions、AWS Lambda、Logic Apps、Power Automate、CRM、搜索索引或 AI 服务。

本指南将介绍 SitecoreAI CMS 层当前已记录的所有 Webhook 功能：架构、有效负载、安全指南以及生产模式。

SitecoreAI 中的三大 Webhook 生态系统

SitecoreAI 的 Webhook 功能分为三个不同的类别，分别覆盖平台的不同层级：

1. CMS 与工作流 Webhook 涵盖创作活动：项目更改、发布以及工作流过渡。在 Content Editor / Pages 中配置。
2. 表单 Webhook 涵盖访客在表单上的行为：浏览、交互和提交。
3. Experience Edge Admin API Webhook：在发布完成后触发，内容已落地到 Edge 时触发。

第四个相关功能——审计日志 Webhook——存在于 Sitecore Cloud Portal 层级。它是一个租户级安全功能，涵盖您使用的每个 Sitecore 产品，并非 CMS 内容 Webhook，因此将在下文单独介绍，而不会与上述三者混为一谈。

1. CMS 与工作流 Webhook

这些位于内容树中的 /sitecore/system/Webhooks 之下。查看或创建它们需要开发者或管理员角色。该伞形下有三种不同的机制。

Webhook 事件处理器：Fire-and-Forget 通知

在订阅的系统事件发生时异步触发，不会阻塞作者。适用于搜索索引、缓存失效、CRM 同步、分析 ping 等不应该拖慢编辑体验的操作。

Sitecore 记录了 18 个受支持的 Webhook 事件：14 个涵盖项目生命周期，4 个涵盖发布。

项目级事件：
item:added、item:cloneAdded、item:copied、item:deleted、item:deleting、item:locked、item:moved、item:renamed、item:saved、item:sortorderChanged、item:templateChanged、item:unlocked、item:versionAdded、item:versionRemoved

发布级事件：
publish:begin、publish:end、publish:fail、publish:statusUpdated

您最常使用的： item:saved（一次编辑会话中可能触发多次）、item:added、item:deleted 以及 publish:end。

切勿在没有规则的情况下订阅。 未加作用域的 item:saved 处理器会在整个内容树中每一次细微字段编辑和树重排序时触发。使用规则引擎将其限制在特定模板、分支、站点或语言上。

Webhook 提交操作：工作流过渡通知

直接附加到工作流状态或命令（位于 /sitecore/System/Workflows 下）。当项目进入该状态或命令运行时触发。这就是您在内容进入“已批准”状态时向 Teams 或 Slack 发送消息，或在内容移至“准备翻译”时启动 Smartling 或 Phrase 翻译作业时所使用的功能。

Webhook 验证操作：同步守门员

此操作与其他两种操作的行为不同。事件处理器和提交操作仅通知，而验证操作会暂停工作流命令，等待响应后才进行任何更改。

作者点击“提交审批”
              │
              ▼
  SitecoreAI 发送同步
     验证 Webhook 请求
              │
              ▼
   外部服务评估
          该项目
              │
      ┌───────┴───────┐
      ▼               ▼
   HTTP 200      超时 / 错误 /
                    非 2xx
      │               │
      ▼               ▼
  工作流        工作流被阻止；
  前进        向作者显示错误

进入全屏模式 退出全屏模式

典型用途：SEO 验证、无障碍检查、AI 内容审核、品牌语音合规、法律签字、元数据完整性。如果端点失败、超时或返回非成功响应，则命令中止，项目状态不会更改。

有效负载参考：提交和验证操作

两种操作类型发送相同的有效负载结构：

属性	类型	描述
ActionID	GUID	发送该 Webhook 的处理器项目 ID
ActionName	String	该处理器项目的名称
Comments	Array of Key/Value objects	过渡期间输入的评论
DataItem	Object	完整项目：语言、版本、ID、模板、字段
Message	String	附加消息文本（如果有）
NextState	Object	项目即将进入的工作流状态
PreviousState	Object	项目即将离开的工作流状态
UserName	String	发起命令的账号
WorkflowName	String	活动工作流的名称
WebhookItemId	GUID	Webhook 项目本身的 ID

2. SitecoreAI 表单 Webhook

表单开箱即用地支持 Webhook：无需自定义开发。可从表单生成器的“设置”选项卡按表单配置，也可从 Webhook 仪表板集中配置，您可以在仪表板中搜索、筛选并查看哪些 Webhook 正在使用。绑定到已发布表单的 Webhook 会被锁定，无法删除，因此您不会因意外删除其目标而破坏实时表单。

表单会触发三个内置事件（VIEWED、INTERACTED 和 SUBMITTED），并支持自定义事件以实现更精细的跟踪，这在将数据导入 Sitecore CDP 或类似平台时非常有用。

身份验证选项：

类型	设置	适用场景
OAuth 2	Client ID、密钥、认证端点	需要动态 JWT 的企业集成
Basic	用户名和密码	轻量级测试集成
API Key	静态标头键/值	使用固定密钥的服务器到服务器集成
No Authentication	无	仅限本地调试；不推荐用于生产环境

在激活表单之前务必测试 Webhook。测试 Webhook 流程会显示确切的 URL、有效负载和标头，然后才让真实访客数据触达，并用 "test": true 标记测试提交，以便您之后过滤掉这些数据。

3. Experience Edge Admin API Webhook

一旦发布将内容落地到 Experience Edge，您可以通过两种执行模式触发下游系统（静态站点重建、CDN 清除、搜索索引更新、数据湖同步）：

模式	行为	适用场景
OnEnd（默认）	在整个发布作业完成后触发一次	CI/CD 触发、全量缓存清除
OnUpdate	按实体触发，有效负载中包含具体变更	增量/差量搜索更新、事件流

有两点值得注意的事项通常不会出现在教程中：如果您使用的是 Edge 运行时发布（v2）而非旧版快照发布（v1），您会看到每个作业的 Webhook 触发次数减少，因为 v2 每次运行发布的项目集更小。Edge 会独立监控其 Webhook 健康状况：如果某个 Webhook 连续 10 次尝试在 30 秒内未响应，Edge 会自动禁用它。您需要在接收端修复后，通过 Admin API 重新启用它。

超出 CMS：Sitecore Cloud Portal 上的审计日志 Webhook

值得了解，尽管属于完全不同的层级：Sitecore Common Audit Log 由 Sitecore Cloud Portal 管理，可通过其自身的 Webhook REST API，将来自每个受支持的 Sitecore DXP 应用程序的安全和访问事件（登录、角色更改、记录创建/编辑/删除）流式传输到外部系统（如 SIEM）。它是租户级的（涵盖您 Sitecore 组织中的所有内容，而不仅仅是 SitecoreAI 内容），使用 bearer-token 身份验证，且配置完全独立于内容树中的任何内容。如果您的集成路线图包含集中式安全监控，值得一看，但请不要将其与上述内容级 Webhook 混淆；它们是名称相同但毫不相关的系统。

企业架构模式

模式 1：搜索索引同步

   作者发布内容
              │
              ▼
  Experience Edge 处理
       该发布
              │
              ▼  (OnEnd webhook)
      Azure Function
              │
              ▼  (通过 GraphQL
                  查询 Edge 的已渲染字段)
   搜索索引 (Algolia / Coveo)
        (部分更新)

进入全屏模式 退出全屏模式

1. 创建一个设置为 OnEnd 的 Experience Edge Admin Webhook（或作用域限定为 publish:end 的 CMS 级事件处理器，具体取决于您是对 Edge 端还是 CMS 端完成做出反应）。
2. 将其限制为您实际需要索引的模板，例如 Article Page。
3. 您的接收器提取变更的项目 ID，通过 Experience Edge GraphQL 端点查询已渲染的字段，并将部分更新推送到您的索引，通常在发布后数秒内完成。

优势：近实时索引、小型有效负载、最小化常驻基础设施。

模式 2：AI 驱动的工作流验证守门员

  作者点击“提交审批”
              │
              ▼
   Webhook 验证操作
      同步触发
              │
              ▼
  Azure Function + LLM 评估器
     检查 DataItem.Fields
              │
      ┌───────┴───────┐
      ▼               ▼
 满足条件     不满足条件
  HTTP 200        HTTP 400 +
                  {"message": "..."}
      │               │
      ▼               ▼
  工作流         工作流被阻止；
  前进         向作者显示错误

进入全屏模式 退出全屏模式

1. 将 Webhook 验证操作添加到相关工作流命令。
2. 您的接收服务评估 DataItem.Fields：缺少的元描述、标题长度、无障碍缺口、偏离品牌语言，涵盖您规则中的所有内容。
3. 返回 HTTP 200 表示通过，或返回 HTTP 400 并附带清晰消息表示失败；SitecoreAI 会将该消息直接在 UI 中展示给作者。

生产最佳实践

快速响应，异步处理

SitecoreAI 的 CMS 级 Webhook 请求默认超时时间为 10 秒。如果您的端点在行内执行任何更重的操作（批量图像生成、多页爬取、慢速 LLM 调用），您将会超时。立即以 HTTP 202 Accepted 响应，并将有效负载交给队列（Azure Service Bus、Azure Storage Queue、Amazon SQS、RabbitMQ、Kafka），然后在后台处理。

为幂等性而设计：理由充分

仍然值得让接收器设计为无论处理同一事件多少次都产生相同结果，但原因并非 SitecoreAI 会重试失败的投递。它不会。 如果您的端点出错或超时，Sitecore 不会自动重新发送请求，且该失败不会出现在任何地方，除非您自己的日志。真正需要构建幂等性的原因是，单一创作操作可能会合法地多次触发同一事件。例如 item:saved 在一次简单编辑期间可能触发多次，因此无论如何，您的接收器都需要优雅地处理重复。好的幂等性键包括：WebhookItemId、项目 ID 加修订版，或发布作业 ID。

保护每个端点

• 始终仅使用 HTTPS
• 每个 Webhook 都需带授权项（API 密钥、OAuth 2.0 或 Basic）：切勿发布匿名的生产端点
• 轮换密钥，并将其存储在 Azure Key Vault 或 AWS Secrets Manager 中，而非应用配置
• 在基础设施支持的情况下进行 IP 白名单限制

刻意限定 Webhook 作用域

全局、无作用域的事件处理器是团队意外使自身集成过载的最常见方式。使用规则引擎按模板、内容分支、站点或语言限制执行：您跳过的每条规则都是您本不需要支付的 HTTP 流量、重复处理和基础设施成本。

监控一切

使用您已有的可观测性工具跟踪响应时间、失败次数和队列深度：Application Insights、Datadog、Splunk、Elastic、Grafana。由于 SitecoreAI 不会代表您重试失败的 CMS 级 Webhook，因此监控是防止静默故障导致搜索索引过时或 CRM 永远不知道新线索的唯一屏障。

示例接收器：Azure Function（.NET 9，隔离工作进程）

[Function("SitecoreAIWebhookReceiver")]
public async Task<HttpResponseData> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req,
    [ServiceBusOutput("sitecoreai-events", Connection = "ServiceBusConnection")]
    IAsyncCollector<string> queue)
{
    string payload = await new StreamReader(req.Body).ReadToEndAsync();

    // 立即推送，不要在行内处理
    await queue.AddAsync(payload);

    // 在 10 秒窗口内确认
    var response = req.CreateResponse(HttpStatusCode.Accepted);
    await response.WriteStringAsync("Webhook received.");
    return response;
}

进入全屏模式 退出全屏模式

此模式确保您的接收器始终处于 SitecoreAI 的超时窗口内，无论下游处理耗时多久。

结语

Webhook 仍是 SitecoreAI CMS 层的主要集成界面：XM Cloud 引入的同一事件驱动模型，如今以新名称运行，并叠加了 AI 能力。无论您是同步搜索索引、用 AI 评估器守卫工作流过渡、将表单线索路由到 CRM，还是将审计事件转发到 SIEM，模式始终如一：快速确认、异步处理、严格限定作用域、对所有内容进行身份验证，并针对重复事件进行设计，而不是假设 Sitecore 会为您重试失败。

根据 2026 年 7 月的 Sitecore 官方 SitecoreAI 文档 (doc.sitecore.com) 验证。