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
For information about endpoint validation with Cloud Events, see [Endpoint validation with CloudEvents 1.0](end-point-validation-cloud-events-schema.md).
Copy file name to clipboardExpand all lines: articles/event-grid/concepts-event-grid-namespaces.md
+3-151Lines changed: 3 additions & 151 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,158 +43,10 @@ Here's a sample event:
43
43
### Another kind of event
44
44
The user community also refers as "events" to messages that carry a data point, such as a single device reading or a click on a web application page. That kind of event is usually analyzed over a time window to derive insights and take an action. In Event Grid’s documentation, we refer to that kind of event as a **data point**, **streaming data**, or simply as **telemetry**. Among other types of messages, this kind of events is used with Event Grid’s Message Queuing Telemetry Transport (MQTT) broker feature.
45
45
46
-
## CloudEvents
47
-
Event Grid namespace topics accepts events that comply with the Cloud Native Computing Foundation (CNCF)’s open standard [CloudEvents 1.0](https://github.com/cloudevents/spec) specification using the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) with [JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md). A CloudEvent is a kind of message that contains what is being communicated, referred to as event data, and metadata about it. The event data in event-driven architectures typically carries the information announcing a system state change. The CloudEvents metadata is composed of a set of attributes that provide contextual information about the message like where it originated (the source system), its type, etc. All valid messages adhering to the CloudEvents specifications must include the following required [context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes):
46
+
## Support for CloudEvents
47
+
Event Grid namespace topics accepts events that comply with the Cloud Native Computing Foundation (CNCF)’s open standard [CloudEvents 1.0](https://github.com/cloudevents/spec) specification using the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) with [JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md). A CloudEvent is a kind of message that contains what is being communicated, referred to as event data, and metadata about it. The event data in event-driven architectures typically carries the information announcing a system state change. The CloudEvents metadata is composed of a set of attributes that provide contextual information about the message like where it originated (the source system), its type, etc.
The CloudEvents specification also defines [optional](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#optional-attributes) and [extension context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#extension-context-attributes) that you can include when using Event Grid.
55
-
56
-
When using Event Grid, CloudEvents is the preferred event format because of its well-documented use cases ([modes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#13-content-modes) for transferring events, [event formats](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#14-event-formats), etc.), extensibility, and improved interoperability. CloudEvents improves interoperability by providing a common event format for publishing and consuming events. It allows for uniform tooling and standard ways of routing & handling events.
57
-
58
-
### CloudEvents content modes
59
-
60
-
The CloudEvents specification defines three [content modes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#13-content-modes): [binary](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#31-binary-content-mode), [structured](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#32-structured-content-mode), and [batched](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode).
61
-
62
-
>[!IMPORTANT]
63
-
> With any content mode you can exchange text (JSON, text/*, etc.) or binary-encoded event data. The binary content mode is not exclusively used for sending binary data.
64
-
65
-
The content modes aren't about the encoding you use, binary, or text, but about how the event data and its metadata are described and exchanged. The structured content mode uses a single structure, for example, a JSON object, where both the context attributes and event data are together in the HTTP payload. The binary content mode separates context attributes, which are mapped to HTTP headers, and event data, which is the HTTP payload encoded according to the media type set in ```Content-Type```.
66
-
67
-
### CloudEvents support
68
-
69
-
This table shows the current support for CloudEvents specification:
|[Structured JSON batched](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode)| Yes, for publishing events |
75
-
|[Binary](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#31-binary-content-mode)| Yes, for publishing events|
76
-
77
-
The maximum allowed size for an event is 1 MB. Events over 64 KB are charged in 64-KB increments.
78
-
79
-
### Structured content mode
80
-
81
-
A message in CloudEvents structured content mode has both the context attributes and the event data together in an HTTP payload.
82
-
83
-
>[!Important]
84
-
> Currently, Event Grid supports the [CloudEvents JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md) with HTTP.
85
-
86
-
Here's an example of a CloudEvents in structured mode using the JSON format. Both metadata (all attributes that aren't "data") and the message/event data (the "data" object) are described using JSON. Our example includes all required context attributes along with some optional attributes (`subject`, `time`, and `datacontenttype`) and extension attributes (`comexampleextension1`, `comexampleothervalue`).
87
-
88
-
```json
89
-
{
90
-
"specversion" : "1.0",
91
-
"type" : "com.yourcompany.order.created",
92
-
"source" : "/orders/account/123",
93
-
"subject" : "O-28964",
94
-
"id" : "A234-1234-1234",
95
-
"time" : "2018-04-05T17:31:00Z",
96
-
"comexampleextension1" : "value",
97
-
"comexampleothervalue" : 5,
98
-
"datacontenttype" : "application/json",
99
-
"data" : {
100
-
"orderId" : "O-28964",
101
-
"URL" : "https://com.yourcompany/orders/O-28964"
102
-
}
103
-
}
104
-
```
105
-
106
-
You can use the JSON format with structured content to send event data that isn't a JSON value. To that end, you do the following steps:
107
-
108
-
1. Include a ```datacontenttype``` attribute with the media type in which the data is encoded.
109
-
1. If the media type is encoded in a text format like ```text/plain```, ```text/csv```, or ```application/xml```, you should use a ```data``` attribute with a JSON string containing what you are communicating as value.
110
-
1. If the media type represents a binary encoding, you should use a ```data_base64``` attribute whose value is a [JSON string](https://tools.ietf.org/html/rfc7159#section-7) containing the [BASE64](https://tools.ietf.org/html/rfc4648#section-4) encoded binary value.
111
-
112
-
For example, this CloudEvent carries event data encoded in ```application/protobuf``` to exchange Protobuf messages.
For more information on the use of the ```data``` or ```data_base64``` attributes, see [Handling of data](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md#31-handling-of-data) .
127
-
128
-
For more information about this content mode, see the CloudEvents [HTTP structured content mode specifications](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#32-structured-content-mode) .
129
-
130
-
### Batched content mode
131
-
132
-
Event Grid currently supports the [JSON batched content mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md#4-json-batch-format) when **publishing** CloudEvents to Event Grid. This content mode uses a JSON array filled with CloudEvents in structured content mode. For example, your application can publish two events using an array like the following. Likewise, if you're using Event Grid's [data plane SDK](https://azure.github.io/azure-sdk/releases/latest/java.html), this payload is also what is being sent:
133
-
134
-
```json
135
-
[
136
-
{
137
-
"specversion": "1.0",
138
-
"id": "E921-1234-1235",
139
-
"source": "/mycontext",
140
-
"type": "com.example.someeventtype",
141
-
"time": "2018-04-05T17:31:00Z",
142
-
"data": "some data"
143
-
},
144
-
{
145
-
"specversion": "1.0",
146
-
"id": "F555-1234-1235",
147
-
"source": "/mycontext",
148
-
"type": "com.example.someeventtype",
149
-
"time": "2018-04-05T17:31:00Z",
150
-
"data": {
151
-
"somekey" : "value",
152
-
"someOtherKey" : 9
153
-
}
154
-
}
155
-
]
156
-
```
157
-
158
-
For more information, see CloudEvents [Batched Content Mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode) specs.
159
-
160
-
### Batching
161
-
162
-
Your application should batch several events together in an array to attain greater efficiency and higher throughput with a single publishing request. Batches can be up to 1 MB and the maximum size of an event is 1 MB.
163
-
164
-
### Binary content mode
165
-
166
-
A CloudEvent in binary content mode has its context attributes described as HTTP headers. The names of the HTTP headers are the name of the context attribute prefixed with ```ce-```. The ```Content-Type``` header reflects the media type in which the event data is encoded.
167
-
168
-
>[!IMPORTANT]
169
-
> When using the binary content mode the ```ce-datacontenttype``` HTTP header MUST NOT also be present.
170
-
171
-
>[!IMPORTANT]
172
-
> If you are planning to include your own attributes (i.e. extension attributes) when using the binary content mode, make sure that their names consist of lower-case letters ('a' to 'z') or digits ('0' to '9') from the ASCII character and that they do not exceed 20 characters in length. That is, the naming convention for [naming CloudEvents context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#attribute-naming-convention) is more restrictive than that of valid HTTP header names. Not every valid HTTP header name is a valid extension attribute name.
173
-
174
-
The HTTP payload is the event data encoded according to the media type in ```Content-Type```.
175
-
176
-
An HTTP request used to publish a CloudEvent in content binary mode can look like this example:
Binary data according to protobuf encoding format. No context attributes are included.
191
-
```
192
-
193
-
### When to use CloudEvents' binary or structured content mode
194
-
195
-
You could use structured content mode if you want a simple approach for forwarding CloudEvents across hops and protocols. Since a CloudEvent in structured content mode contains the message together with its metadata, it's easy for clients to consume it as a whole and forward it to other systems.
196
-
197
-
You could use binary content mode if you know downstream applications require only the message without any extra information (that is, the context attributes). While with structured content mode you can still get the event data (message) out of the CloudEvent, it's easier if a consumer application just has it in the HTTP payload. For example, other applications can use other protocols and may be interested only in your core message, not its metadata. In fact, the metadata could be relevant just for the immediate first hop. In this case, having the data that you want to exchange apart from its metadata lends itself to easier handling and forwarding.
49
+
For more information, see [Support for CloudEvents schema](namespaces-cloud-events.md).
title: Endpoint validation with CloudEvents schema
3
+
description: This article describes WebHook event delivery and endpoint validation when using webhooks and CloudEvents v1.0 schema.
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
+
# Endpoint validation with CloudEvents schema
11
+
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.
12
+
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
+
15
+
## Endpoint validation with CloudEvents v1.0
16
+
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.
17
+
18
+
### CloudEvent v1.0 abuse protection
19
+
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.
20
+
21
+
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.
22
+
23
+
Reaching the delivery agreement is realized using the following validation handshake. The handshake can either be executed immediately at registration time
24
+
or as a "preflight" request immediately preceding a delivery.
25
+
26
+
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
27
+
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.
28
+
29
+
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.
30
+
31
+
### Validation request
32
+
33
+
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.
34
+
35
+
#### WebHook-Request-Origin
36
+
37
+
The `WebHook-Request-Origin` header MUST be included in the validation request and requests permission to send notifications from this sender, and contains a
38
+
Domain Name System (DNS) expression that identifies the sending system, for example `eventemitter.example.com`. The value is meant to summarily identify all sender
39
+
instances that act on the behalf of a certain system, and not an individual host.
40
+
41
+
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
42
+
of this header.
43
+
44
+
Example:
45
+
46
+
```bash
47
+
WebHook-Request-Origin: eventemitter.example.com
48
+
```
49
+
50
+
### Validation response
51
+
52
+
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
53
+
`WebHook-Allowed-Rate` headers. If the delivery target chooses to grant permission by callback, it withholds the response headers.
54
+
55
+
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
56
+
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
57
+
handle the HTTP OPTIONS method, it SHOULD respond with HTTP status code 405, as if OPTIONS weren't supported.
58
+
59
+
The OPTIONS response SHOULD include the `Allow` header indicating the POST method being permitted. Other methods MAY be permitted on the
60
+
resource, but their function is outside the scope of this specification.
61
+
62
+
### WebHook-Allowed-Origin
63
+
64
+
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
65
+
the origin name supplied in the `WebHook-Request-Origin` header, or a singular asterisk character ('\*'), indicating that the delivery target supports
66
+
notifications from all origins.
67
+
68
+
```bash
69
+
WebHook-Allowed-Origin: eventemitter.example.com
70
+
```
71
+
72
+
Or
73
+
74
+
```bash
75
+
WebHook-Request-Origin: *
76
+
```
77
+
78
+
> [!IMPORTANT]
79
+
> 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).
80
+
81
+
82
+
## Related content
83
+
See the following article to learn how to troubleshoot event subscription validations: [Troubleshoot event subscription validations](troubleshoot-subscription-validation.md).
0 commit comments