You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/event-grid/end-point-validation-event-grid-events-schema.md
+1-68Lines changed: 1 addition & 68 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: Endpoint validation with Event Grid event schema
3
3
description: This article describes WebHook event delivery and endpoint validation when using webhooks and the Event Grid event schema.
4
4
ms.topic: concept-article
5
-
ms.date: 09/25/2023
5
+
ms.date: 09/25/2024
6
6
#customer intent: As a developer, I want to know hw to validate a Webhook endpoint using the Event Grid event schema.
7
7
---
8
8
@@ -12,73 +12,6 @@ Webhooks are one of the many ways to receive events from Azure Event Grid. When
12
12
13
13
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.
14
14
15
-
16
-
## Endpoint validation with CloudEvents v1.0
17
-
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.
18
-
19
-
### CloudEvent v1.0 abuse protection
20
-
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.
21
-
22
-
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.
23
-
24
-
Reaching the delivery agreement is realized using the following validation handshake. The handshake can either be executed immediately at registration time
25
-
or as a "preflight" request immediately preceding a delivery.
26
-
27
-
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
28
-
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.
29
-
30
-
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.
31
-
32
-
### Validation request
33
-
34
-
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.
35
-
36
-
#### WebHook-Request-Origin
37
-
38
-
The `WebHook-Request-Origin` header MUST be included in the validation request and requests permission to send notifications from this sender, and contains a
39
-
Domain Name System (DNS) expression that identifies the sending system, for example `eventemitter.example.com`. The value is meant to summarily identify all sender
40
-
instances that act on the behalf of a certain system, and not an individual host.
41
-
42
-
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
43
-
of this header.
44
-
45
-
Example:
46
-
47
-
```bash
48
-
WebHook-Request-Origin: eventemitter.example.com
49
-
```
50
-
51
-
### Validation response
52
-
53
-
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
54
-
`WebHook-Allowed-Rate` headers. If the delivery target chooses to grant permission by callback, it withholds the response headers.
55
-
56
-
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
57
-
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
58
-
handle the HTTP OPTIONS method, it SHOULD respond with HTTP status code 405, as if OPTIONS weren't supported.
59
-
60
-
The OPTIONS response SHOULD include the `Allow` header indicating the POST method being permitted. Other methods MAY be permitted on the
61
-
resource, but their function is outside the scope of this specification.
62
-
63
-
### WebHook-Allowed-Origin
64
-
65
-
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
66
-
the origin name supplied in the `WebHook-Request-Origin` header, or a singular asterisk character ('\*'), indicating that the delivery target supports
67
-
notifications from all origins.
68
-
69
-
```bash
70
-
WebHook-Allowed-Origin: eventemitter.example.com
71
-
```
72
-
73
-
Or
74
-
75
-
```bash
76
-
WebHook-Request-Origin: *
77
-
```
78
-
79
-
> [!IMPORTANT]
80
-
> 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).
81
-
82
15
## Endpoint validation with Event Grid events
83
16
When you use any of the following three Azure services, the Azure infrastructure automatically handles this validation:
description: When a subscription is created, an outgoing event schema is defined. The following table shows you the compatibility allowed when creating a subscription.
4
+
ms.topic: concept-article
5
+
ms.date: 09/25/2024
6
+
#customer intent: As a developer, I want to know hw to validate a Webhook endpoint using the CloudEvents v1.0 schema.
7
+
---
8
+
9
+
10
+
# Event schema compatibility
11
+
When a topic is created, an incoming event schema is defined. And, when a subscription is created, an outgoing event schema is defined. This article shows you the compatibility between input and output schema that's allowed when creating an event subscription.
12
+
13
+
## Input schema to outupt schema
14
+
The following table shows you the compatibility allowed when creating a subscription.
See the following article to learn how to troubleshoot event subscription validations: [Troubleshoot event subscription validations](troubleshoot-subscription-validation.md).
0 commit comments