WebHook 事件傳遞

發行項
03/11/2024

Webhook 是從 Azure 事件方格接收事件的眾多方法之一。當新事件準備就緒時，「事件方格」服務就會透過 POST 對所設定的端點發佈 HTTP 要求，並在要求本文內夾帶該事件資訊。

和許多其他支援 Webhook 的服務一樣，「事件方格」也會先要求您證明具有 Webhook 端點的「擁有權」，然後才開始將事件傳遞給該端點。此需求可避免惡意使用者利用事件癱瘓您的端點。

使用事件方格事件進行端點驗證

當您使用下列三種 Azure 服務的任一種時，Azure 基礎結構將會自動處理這項驗證：

Azure Logic Apps，使用事件格線連接器進行驗證
Azure 自動化，透過 Webhook 進行驗證
Azure Functions，使用事件格線觸發程序進行驗證

如果您使用任何其他類型的端點 (例如以 HTTP 觸發程序為基礎的 Azure 函式)，則您的端點程式碼必須參與和「事件方格」的驗證交握。「事件方格」支援兩種驗證訂用帳戶的方式。

同步交握：建立事件訂閱時，事件方格會將訂閱驗證事件傳送至您的端點。此事件的結構描述類似於任何其他「事件方格」事件。此事件的資料部分包含 validationCode 屬性。您的應用程式會確認該驗證要求是針對預期的事件訂閱，然後以同步方式在回應中傳回驗證碼。所有「事件方格」版本都支援此交握機制。
非同步交握：在某些情況下，您無法在回應中同步傳回 validationCode。例如，如果您使用第三方服務 (例如 Zapier 或 IFTTT)，就無法透過程式設計方式以驗證碼回應。

事件方格支援手動驗證交握。如果您是以採用 API 2018-05-01-preview 版或更新版本的 SDK 或工具來建立事件訂閱，「事件方格」就會在訂閱驗證事件的資料部分中一併傳送 validationUrl 屬性。若要完成交握，請在事件資料中找出該 URL，然後對其提出 GET 要求。您可以使用 REST 用戶端或您的網頁瀏覽器。

提供的 URL 有效期限為 10 分鐘。在那段時間，事件訂閱的佈建狀態為 AwaitingManualAction。如果您在 10 分鐘內未完成手動驗證，布建狀態會設定為 Failed。您必須再次建立事件訂閱，才能開始進行手動驗證。

此驗證機制也需要 Webhook 端點傳回 HTTP 狀態碼 200，以便其得知已先接受驗證事件的 POST，才能進入手動驗證模式。換句話說，如果端點傳回 200，但並未同步傳回驗證回應，則模式會轉換成手動驗證模式。如果在 10 分鐘內有驗證 URL 上的 GET，驗證交握會被視為成功。

注意

不支援使用自我簽署憑證進行驗證。請改用商業憑證授權單位 (CA) 所簽署的憑證。

驗證詳細資料

建立/更新事件訂閱時，「事件方格」會將訂閱驗證事件發佈至目標端點。
此事件會包含一個標頭值 aeg-event-type: SubscriptionValidation。
此事件主體之結構描述與其他 Event Grid 事件相同。
事件的 eventType 屬性為 Microsoft.EventGrid.SubscriptionValidationEvent。
事件的 data 屬性包含 validationCode 屬性，內含隨機產生的字串。例如： validationCode: acb13… 。
事件資料也包含具有 URL 的 validationUrl 屬性，可供手動驗證訂用帳戶。
此陣列只包含驗證事件。在您回應驗證程式碼之後，其他事件會在不同的要求中傳送。
EventGrid 資料平面 SDK 具有對應至訂用帳戶驗證事件資料和訂用帳戶驗證回應的類別。

下列範例顯示 SubscriptionValidationEvent 的範例：

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2022-10-28T04:23:35.1981776Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

如需證明端點擁有權，請在 validationResponse 屬性中回應驗證代碼，如下列範例所示：

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

然後，執行下列其中一個步驟：

您必須傳回 HTTP 200 正常回應狀態碼。 HTTP 202 已接受無法辨識為有效的事件方格訂用帳戶驗證回應。此 HTTP 要求必須在 30 秒內完成。如果作業未在 30 秒內完成，則會取消作業，而且可能會在 5 秒後重新嘗試。若所有嘗試都失敗，則會將其視為驗證交握錯誤。

如果您的應用程式已準備好處理並傳回驗證碼，表示您已建立事件訂用帳戶，且預期會收到事件。設想若沒有支援的交握驗證，且有駭客得知您的應用程式 URL。駭客可以使用應用程式的 URL 建立主題和事件訂用帳戶，並藉由傳送大量事件，開始對您的應用程式發動 DoS 攻擊。交握驗證可防止這種情況發生。

設想您建立了自己的事件訂用帳戶，因此已在應用程式中實作驗證。即便駭客使用您的應用程式 URL 建立事件訂用帳戶，驗證要求事件的正確實作仍會檢查要求中是否有 aeg-subscription-name 標頭，以確定這是您認可的事件訂用帳戶。

即使完成了這個正確的交握實作，駭客仍可藉由複寫看似來自事件方格的要求，使您的應用程式 (已驗證事件訂用帳戶) 癱瘓。若要避免此狀況發生，您必須使用 Microsoft Entra 驗證保護 Webhook。如需詳細資訊，請參閱將事件傳遞至受 Microsoft Entra 保護的端點。
或者，您可以藉由將 GET 要求傳送至驗證 URL，以手動方式驗證訂用帳戶。事件訂用帳戶會保持擱置狀態，直到通過驗證為止。驗證 URL 會使用連接埠 553。如果防火牆規則封鎖了連接埠 553，您將必須更新規則才能成功進行手動交握。

在訂用帳戶驗證事件的驗證中，如果您發現其並非您預期事件的事件訂用帳戶，則不會傳回 200 回應，或根本不會有回應。因此，驗證會失敗。

如需有關處理訂閱驗證交握的範例，請參閱 C# 範例 \(英文\)。

使用 CloudEvents v1.0 進行端點驗證

CloudEvents v1.0 會使用 HTTP OPTIONS 方法，實作其本身的濫用保護語意。您可以在此處閱讀相關資訊。使用 CloudEvents 結構描述進行輸出時，事件方格會使用 CloudEvents v1.0 濫用保護來取代事件方格驗證事件機制。

事件結構描述相容性

建立主題時，會定義傳入的事件結構描述。建立訂用帳戶時，也會定義傳出的事件結構描述。下表向您顯示建立訂用帳戶時允許的相容性。

傳入事件結構描述	傳出事件結構描述	支援
事件方格結構描述	事件方格結構描述	Yes
	雲端事件 v1.0 結構描述	Yes
	自訂輸入結構描述	No
雲端事件 v1.0 結構描述	事件方格結構描述	No
	雲端事件 v1.0 結構描述	Yes
	自訂輸入結構描述	No
自訂輸入結構描述	事件方格結構描述	Yes
	雲端事件 v1.0 結構描述	Yes
	自訂輸入結構描述	Yes

下一步

請參閱下列文章，了解如何針對事件訂用帳戶驗證進行疑難排解：針對事件訂用帳戶驗證進行疑難排解。

WebHook 事件傳遞

使用事件方格事件進行端點驗證

驗證詳細資料

使用 CloudEvents v1.0 進行端點驗證

事件結構描述相容性

下一步

其他資源