Separate articles for endpoint validation

Author: spelluru

articles/event-grid/.openpublishing.redirection.event-grid.json

@@ -1,5 +1,10 @@
 {
   "redirections": [    
+    {
+      "source_path": "webhook-event-delivery.md",
+      "redirect_url": "/azure/event-grid/end-point-validation-cloud-events-schema.md",
+      "redirect_document_id": false
+    },    
     {
       "source_path": "cloudevents-schema.md",
       "redirect_url": "/azure/event-grid/cloud-event-schema",

articles/event-grid/cloud-event-schema.md

@@ -185,4 +185,4 @@ If you're using the Azure portal to develop an Azure function, follow these step
 
 
 ## Related content
-For information about endpoint validation with Cloud Events, see [Endpoint validation with CloudEvents 1.0](webhook-event-delivery.md#endpoint-validation-with-cloudevents-v10).
+For information about endpoint validation with Cloud Events, see [Endpoint validation with CloudEvents 1.0](end-point-validation-cloud-events-schema.md).

articles/event-grid/delivery-properties.md

@@ -110,5 +110,5 @@ For the Azure Storage Queues destination, you can only configure the time-to-liv
 For more information about event delivery, see the following article:
 
 - [Delivery and retry](delivery-and-retry.md)
-- [Webhook event delivery](webhook-event-delivery.md)
+- [Endpoint validation](end-point-validation-cloud-events-schema.md)
 - [Event filtering](event-filtering.md)

articles/event-grid/end-point-validation-cloud-events-schema.md

@@ -0,0 +1,98 @@
+---
+title: Endpoint validation with CloudEvents schema
+description: This article describes WebHook event delivery and endpoint validation when using webhooks and CloudEvents v1.0 schema.
+ms.topic: concept-article
+ms.date: 09/25/2023
+#customer intent: As a developer, I want to know hw to validate a Webhook endpoint using the CloudEvents v1.0 schema.
+---
+
+
+# Endpoint validation with CloudEvents schema
+Webhooks are one of the many ways to receive events from Azure Event Grid. When a new event is ready, Event Grid service POSTs an HTTP request to the configured endpoint with the event information in the request body.
+
+Like many other services that support webhooks, Event Grid requires you to prove ownership of your Webhook endpoint before it starts delivering events to that endpoint. This requirement prevents a malicious user from flooding your endpoint with events. 
+
+## Endpoint validation with CloudEvents v1.0
+CloudEvents v1.0 implements its own abuse protection semantics using the **HTTP OPTIONS** method. When you use the CloudEvents schema for output, Event Grid uses the CloudEvents v1.0 abuse protection in place of the Event Grid validation event mechanism.
+
+### CloudEvent v1.0 abuse protection
+Any system that allows registration of and delivery of notifications to arbitrary HTTP endpoints can potentially be abused such that someone maliciously or inadvertently registers the address of a system that doesn't expect such requests and for which the registering party isn't authorized to perform such a registration. In extreme cases, a notification infrastructure could be abused to launch denial-of-service attacks against an arbitrary web-site.
+
+To protect the sender from being abused in such a way, a legitimate delivery target needs to indicate that it agrees with notifications being delivered to it.
+
+Reaching the delivery agreement is realized using the following validation handshake. The handshake can either be executed immediately at registration time
+or as a "preflight" request immediately preceding a delivery.
+
+It's important to understand that the handshake doesn't aim to establish an authentication or authorization context. It only serves to protect the sender
+from being told to a push to a destination that isn't expecting the traffic. While this specification mandates use of an authorization model, this mandate isn't sufficient to protect any arbitrary website from unwanted traffic if that website doesn't implement access control and therefore ignores the `Authorization` header.
+
+Delivery targets SHOULD support the abuse protection feature. If a target doesn't support the feature, the sender MAY choose not to send to the target, at all, or send only at a very low request rate.
+
+### Validation request
+
+The validation request uses the **HTTP OPTIONS** method. The request is directed to the exact resource target URI that is being registered. With the validation request, the sender asks the target for permission to send notifications, and it can declare a desired request rate (requests per minute). The delivery target will respond with a permission statement and the permitted request rate. Here's a couple of the header fields are for inclusion in the validation request.
+
+#### WebHook-Request-Origin
+
+The `WebHook-Request-Origin` header MUST be included in the validation request and requests permission to send notifications from this sender, and contains a
+Domain Name System (DNS) expression that identifies the sending system, for example `eventemitter.example.com`. The value is meant to summarily identify all sender
+instances that act on the behalf of a certain system, and not an individual host.
+
+After the handshake and if permission has been granted, the sender MUST use the `Origin` request header for each delivery request, with the value matching that
+of this header. 
+
+Example:
+
+```bash
+WebHook-Request-Origin: eventemitter.example.com
+```
+
+### Validation response
+
+If and only if the delivery target does allow delivery of the events, it MUST reply to the request by including the `WebHook-Allowed-Origin` and
+`WebHook-Allowed-Rate` headers. If the delivery target chooses to grant permission by callback, it withholds the response headers.
+
+If the delivery target doesn't allow delivery of the events or doesn't expect delivery of events and nevertheless handles the HTTP OPTIONS method, the
+existing response ought not to be interpreted as consent, and therefore the handshake can't rely on status codes. If the delivery target otherwise doesn't
+handle the HTTP OPTIONS method, it SHOULD respond with HTTP status code 405, as if OPTIONS weren't supported.
+
+The OPTIONS response SHOULD include the `Allow` header indicating the POST method being permitted. Other methods MAY be permitted on the
+resource, but their function is outside the scope of this specification.
+
+### WebHook-Allowed-Origin
+
+The `WebHook-Allowed-Origin` header MUST be returned when the delivery target agrees to notification delivery by the origin service. Its value MUST either be
+the origin name supplied in the `WebHook-Request-Origin` header, or a singular asterisk character ('\*'), indicating that the delivery target supports
+notifications from all origins.
+
+```bash
+WebHook-Allowed-Origin: eventemitter.example.com
+```
+
+Or
+
+```bash
+WebHook-Request-Origin: *
+```
+
+> [!IMPORTANT]
+> For more information about the abuse protection, see [Abuse protection in the HTTP 1.1 Web Hooks for event delivery spec](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#4-abuse-protection). 
+
+## Event schema compatibility
+When a topic is created, an incoming event schema is defined. And, when a subscription is created, an outgoing event schema is defined. The following table shows you the compatibility allowed when creating a subscription. 
+
+| Incoming event schema | Outgoing event schema | Supported |
+| ---- | ---- | ---- |
+| Event Grid schema | Event Grid schema | Yes |
+| | Cloud Events v1.0 schema | Yes |
+| | Custom input schema | No |
+| Cloud Events v1.0 schema | Event Grid schema | No |
+| | Cloud Events v1.0 schema | Yes |
+| | Custom input schema | No |
+| Custom input schema | Event Grid schema | Yes |
+| | Cloud Events v1.0 schema | Yes |
+| | Custom input schema | Yes |
+
+
+## Related content
+See the following article to learn how to troubleshoot event subscription validations: [Troubleshoot event subscription validations](troubleshoot-subscription-validation.md).

articles/event-grid/webhook-event-delivery.md renamed to articles/event-grid/end-point-validation-event-grid-events-schema.md

@@ -1,12 +1,13 @@
 ---
-title: WebHook event delivery
-description: This article describes WebHook event delivery and endpoint validation when using webhooks. 
-ms.topic: conceptual
+title: Endpoint validation with Event Grid event schema
+description: This article describes WebHook event delivery and endpoint validation when using webhooks and the Event Grid event schema.
+ms.topic: concept-article
 ms.date: 09/25/2023
+#customer intent: As a developer, I want to know hw to validate a Webhook endpoint using the Event Grid event schema.
 ---
 
 
-# Webhook event delivery
+# # Endpoint validation with Event Grid event schema
 Webhooks are one of the many ways to receive events from Azure Event Grid. When a new event is ready, Event Grid service POSTs an HTTP request to the configured endpoint with the event information in the request body.
 
 Like many other services that support webhooks, Event Grid requires you to prove ownership of your Webhook endpoint before it starts delivering events to that endpoint. This requirement prevents a malicious user from flooding your endpoint with events. 
@@ -170,5 +171,5 @@ When a topic is created, an incoming event schema is defined. And, when a subscr
 | | Custom input schema | Yes |
 
 
-## Next steps
+## Related content
 See the following article to learn how to troubleshoot event subscription validations: [Troubleshoot event subscription validations](troubleshoot-subscription-validation.md).

articles/event-grid/handler-functions.md

@@ -16,7 +16,7 @@ To use a function in Azure as a handler for events, follow one of these approach
 -	Use [HTTP trigger](../azure-functions/functions-bindings-http-webhook.md).  Specify **Web Hook** as the **endpoint type**. Then, specify the URL for the function that will handle events. 
 
 We recommend that you use the first approach (Event Grid trigger) as it has the following advantages over the second approach:
--	Event Grid automatically validates Event Grid triggers. With generic HTTP triggers, you must implement the [validation response](webhook-event-delivery.md) yourself.
+-	Event Grid automatically validates Event Grid triggers. With generic HTTP triggers, you must implement the [validation response](end-point-validation-event-grid-events-schema.md) yourself.
 -	Event Grid automatically adjusts the rate at which events are delivered to a function triggered by an Event Grid event based on the perceived rate at which the function can process events. This rate match feature averts delivery errors that stem from the inability of a function to process events as the function’s event processing rate can vary over time. To improve efficiency at high throughput, enable batching on the event subscription. For more information, see [Enable batching](#enable-batching).
 
 > [!NOTE]

articles/event-grid/kubernetes/event-handlers.md

@@ -45,7 +45,7 @@ Event Grid on Kubernetes offers a good level of feature parity with Azure Event
 5. Only CloudEvents schema is supported. The supported schema value is "[CloudEventSchemaV1_0](/rest/api/eventgrid/controlplane-preview/event-subscriptions/create-or-update#eventdeliveryschema)". Cloud Events schema is extensible and based on open standards.
 6. Labels ([properties.labels](/rest/api/eventgrid/controlplane-preview/event-subscriptions/create-or-update#request-body)) aren't applicable to Event Grid on Kubernetes. Hence, they aren't available.
 7. [Delivery with resource identity](/rest/api/eventgrid/controlplane-preview/event-subscriptions/create-or-update#deliverywithresourceidentity) isn't supported. So, all properties for [Event Subscription Identity](/rest/api/eventgrid/controlplane-preview/event-subscriptions/create-or-update#eventsubscriptionidentity) aren't supported.
-8. [Destination endpoint validation](../webhook-event-delivery.md#endpoint-validation-with-event-grid-events) isn't supported yet.
+8. [Destination endpoint validation](../end-point-validation-cloud-events-schema.md) isn't supported yet.
 
 ## Event filtering in event subscriptions
 The other important aspect of configuring an event subscription is selecting the events that are meant to be delivered to a destination. For more information, see [Event Filtering](filter-events.md).

articles/event-grid/kubernetes/features.md

@@ -33,7 +33,7 @@ Although Event Grid on Kubernetes and Azure Event Grid share many features and t
 | [System Topics](../system-topics.md) | ✘ | ✔ |
 | [Domain Topics](../event-domains.md) | ✘ | ✔ |
 | [Partner Events](../partner-events-overview.md) | ✘ | ✔ |
-| [Destination endpoint validation](../webhook-event-delivery.md#endpoint-validation-with-event-grid-events) | ✘ | ✔ |
+| [Destination endpoint validation](../end-point-validation-cloud-events-schema.md) | ✘ | ✔ |
 | [Azure Event Grid trigger for Azure Functions](../../azure-functions/functions-bindings-event-grid-trigger.md) | ✘ | ✔ |
 | Azure Relay's Hybrid Connections as a destination | ✘ | ✔ |
 | [Advanced filtering](filter-events.md) | ✔*** | ✔ |

articles/event-grid/receive-events.md

@@ -10,7 +10,7 @@ ms.custom: devx-track-csharp
 
 # Receive events to an HTTP endpoint
 
-This article describes how to [validate an HTTP endpoint](webhook-event-delivery.md) to receive events from an Event Subscription and then receive and deserialize events. This article uses an Azure Function for demonstration purposes, however the same concepts apply regardless of where the application is hosted.
+This article describes how to [validate an HTTP endpoint](end-point-validation-cloud-events-schema.md) to receive events from an Event Subscription and then receive and deserialize events. This article uses an Azure Function for demonstration purposes, however the same concepts apply regardless of where the application is hosted.
 
 > [!NOTE]
 > We recommend that you use an [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md) when triggering an Azure Function with Event Grid. It provides an easier and quicker integration between Event Grid and Azure Functions. However, note that Azure Functions' Event Grid trigger does not support the scenario where the hosted code needs to control the HTTP status code returned to Event Grid. Given this limitation, your code running on an Azure Function would not be able to return a 5XX error to initiate an event delivery retry by Event Grid, for example.
@@ -27,7 +27,7 @@ SDKs for other languages are available via the [Publish SDKs](./sdk-overview.md#
 
 ## Endpoint validation
 
-The first thing you want to do is handle `Microsoft.EventGrid.SubscriptionValidationEvent` events. Every time someone subscribes to an event, Event Grid sends a validation event to the endpoint with a `validationCode` in the data payload. The endpoint is required to echo this back in the response body to [prove the endpoint is valid and owned by you](webhook-event-delivery.md). If you're using an [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md) rather than a WebHook triggered Function, endpoint validation is handled for you. If you use a third-party API service (like [Zapier](https://zapier.com/) or [IFTTT](https://ifttt.com/)), you might not be able to programmatically echo the validation code. For those services, you can manually validate the subscription by using a validation URL that is sent in the subscription validation event. Copy that URL in the `validationUrl` property and send a GET request either through a REST client or your web browser.
+The first thing you want to do is handle `Microsoft.EventGrid.SubscriptionValidationEvent` events. Every time someone subscribes to an event, Event Grid sends a validation event to the endpoint with a `validationCode` in the data payload. The endpoint is required to echo this back in the response body to [prove the endpoint is valid and owned by you](end-point-validation-cloud-events-schema.md). If you're using an [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md) rather than a WebHook triggered Function, endpoint validation is handled for you. If you use a third-party API service (like [Zapier](https://zapier.com/) or [IFTTT](https://ifttt.com/)), you might not be able to programmatically echo the validation code. For those services, you can manually validate the subscription by using a validation URL that is sent in the subscription validation event. Copy that URL in the `validationUrl` property and send a GET request either through a REST client or your web browser.
 
 In C#, the `ParseMany()` method is used to deserialize a `BinaryData` instance containing one or more events into an array of `EventGridEvent`. If you knew ahead of time that you are deserializing only a single event, you could use the `Parse` method instead.
 

articles/event-grid/secure-webhook-delivery.md

@@ -214,7 +214,7 @@ Back in **Tenant A**, do the following steps:
 
 ## Next steps
 
-* For conceptual information, see [WebHook event delivery](webhook-event-delivery.md).
+* For conceptual information, see [WebHook event delivery](end-point-validation-cloud-events-schema.md).
 * For information about monitoring event deliveries, see [Monitor Event Grid message delivery](monitor-event-delivery.md).
 * For more information about the authentication key, see [Event Grid security and authentication](security-authentication.md).
 * For more information about creating an Azure Event Grid subscription, see [Event Grid subscription schema](subscription-creation-schema.md).