掌握 SitecoreAI 中的 Webhooks：完整企業整合藍圖（2026 版）

SitecoreAI 是 Sitecore 於 2025 年 Symposium 推出的統一平台，作為 XM Cloud 的繼任者，保留了使 XM Cloud 與傳統 Sitecore XP/XM 有所不同的同一事件驅動整合模型。您仍然無法將自訂 .NET 管線處理器或事件處理常式部署到受管理的內容管理層。相反地，每一項有意義的編寫動作（儲存項目、工作流程推進、提交表單、完成發佈）都能觸發一個帶有 JSON（或 XML）承載（payload）的 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

這些 webhook 位於內容樹的 /sitecore/system/Webhooks 之下。檢視或建立它們需要開發人員或管理員角色。此類別下有三種不同的機制。

Webhook Event Handler：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 Submit Action：工作流程轉換通知

直接附加至工作流程狀態或指令（位於 /sitecore/System/Workflows 之下）。當項目進入該狀態或指令執行時觸發。您可利用此功能在內容進入「已核准」狀態時發送 Teams 或 Slack 訊息，或在項目移至「準備翻譯」狀態時啟動 Smartling 或 Phrase 翻譯工作。

Webhook Validation Action：同步守門員

此類型的行為與前兩種不同。Event Handler 與 Submit Action 僅進行通知，而 Validation Action 會暫停工作流程指令並等待回應，然後才允許變更發生。

作者點擊「提交核准」
              │
              ▼
  SitecoreAI 發送同步
     Validation webhook 請求
              │
              ▼
   外部服務評估
          該項目
              │
      ┌───────┴───────┐
      ▼               ▼
   HTTP 200      逾時 / 錯誤 /
                    非 2xx
      │               │
      ▼               ▼
  工作流程        工作流程被阻斷；
  繼續前進        向作者顯示錯誤

進入全螢幕模式 離開全螢幕模式

典型用途：SEO 驗證、無障礙檢查、AI 內容審核、品牌語調合規、法律簽核、元資料完整性。若端點失敗、逾時或回傳非成功狀態，指令將被中止，項目狀態不會改變。

承載參考：Submit 與 Validation Action

兩種動作類型皆傳送相同格式的承載：

屬性	類型	說明
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 支援，無需自訂開發。可從 Form Builder 的「設定」分頁為每個表單進行設定，或從 Webhooks 儀表板集中管理（可搜尋、篩選並檢視哪些 webhook 正在使用）。綁定至已發佈表單的 webhook 會被鎖定，無法刪除，以避免因誤刪目標而影響線上表單。

表單會觸發三種內建事件（VIEWED、INTERACTED、SUBMITTED），並支援自訂事件以進行更細粒度的追蹤，適用於將資料傳送至 Sitecore CDP 等平台。

驗證選項：

類型	設定方式	適用情境
OAuth 2	Client ID、secret、驗證端點	需要動態 JWT 的企業整合
Basic	使用者名稱與密碼	輕量級測試整合
API Key	靜態標頭金鑰/值	具有固定金鑰的伺服器對伺服器通訊
無驗證	無	僅限本機除錯；不建議用於正式環境

啟用表單前請務必先測試 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 會自動停用該 webhook。您需透過 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 層級 Event Handler，視您要回應 Edge 端或 CMS 端完成而定）。
2. 將其限制為您實際需要索引的樣板，例如 Article Page。
3. 您的接收端提取變更的項目 ID，透過 Experience Edge GraphQL 端點查詢轉譯欄位，並在發佈後數秒內將部分更新推送至索引。

優點：近乎即時的索引建置、承載小、基礎架構需求低。

模式 2：AI 驅動的工作流程驗證守門員

  作者點擊「提交核准」
              │
              ▼
   Webhook Validation Action
      同步觸發
              │
              ▼
  Azure Function + LLM 評估器
     檢查 DataItem.Fields
              │
      ┌───────┴───────┐
      ▼               ▼
 符合條件     不符合條件
  HTTP 200        HTTP 400 +
                  {"message": "..."}
      │               │
      ▼               ▼
  工作流程         工作流程被阻斷；
  繼續前進         向作者顯示錯誤

進入全螢幕模式 離開全螢幕模式

1. 將 Webhook Validation Action 新增至相關的工作流程指令。
2. 您的接收服務評估 DataItem.Fields：缺少 meta description、標題長度、無障礙缺口、非品牌語言等您定義的規則。
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不會重試。若您的端點發生錯誤或逾時，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，Isolated Worker）

[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）進行驗證。