Guidelines for NLgov profile for CloudEvents

• Events can be transferred with all standard or application-defined HTTP request methods that support payload body transfers. Events can be also be transferred in HTTP responses and with all HTTP status codes that permit payload body transfers.
• This specification defines three content modes for transferring events:
  • structured (required): HTTP message body contains both event data and metadata attributes; an appropriate event format is used ((non-batching) JSON is the only event format that MUST be supported);
  • batched (optional): HTTP message body contains event data and metadata attributes from multiple events; an appropriate event format is used.
  • binary (required): HTTP message body contains event data as-is; event attributes mapped to HTTP-headers; HTTP Content-Type header declares the media type.
• Received Content-Type header value is:
  • application/cloudevents(+xxxx): structured mode (xxx denotes the used event format)
  • application/cloudevents-batch: batched mode
  • Otherwise: binary mode (Content-Type header declares the media type.)
• Structured content mode:
  • The HTTP message body MUST contain both event data and metadata attributes.
  • The HTTP Content-Type header MUST be set to the media type of an event format (E.g. application/cloudevents+json; charset=UTF-8)
  • The chosen event format defines how all attributes, and data, are represented in the HTTP message body.
  • Implementations MAY include the same HTTP headers as defined for the binary mode (E.g. ce-id).
• Batched content mode:
  • The HTTP message body MUST contain both event data and metadata attributes.
  • The HTTP Content-Type header MUST be set to the media type of an event format (E.g. application/cloudevents-batch+json; charset=UTF-8)
  • The chosen event format defines how a batch of events and all event attributes, and data, are represented.
  • All batched CloudEvents MUST have the same specversion attribute. Other attributes MAY differ, including the datacontenttype attribute. The batch MAY be empty.
• Binary content mode:
  • All CloudEvents context attributes, including extensions, MUST be mapped to HTTP headers with the same name as the attribute name but prefixed with ce-.
  • The value for each HTTP header is constructed as described in the specification

At the moment there are no additional agreements about the use of the specification within the Dutch government.

• One SHOULD use the HTTP Protocol Binding for CloudEvents.
• There are no agreements to deviate from the standard in any part.
• Given the fact that many organizations still have little experience with standardized exchange of events, we recommend a useful relatively simple mechanism that consumers are already familiar with:
  • One SHOULD use structured content mode.
  • One SHOULD use the JSON (non batched) event format
  • When using structured mode one SHOULD NOT depend on the usage of HTTP-headers that replicate context-attributes in the event.
• If the above advice is followed, when notifying via webhooks 1 message will contain JSON-structured data about 1 event that has occurred.

Structured content mode: HTTP POST request with a JSON event format encoded event:

POST /myresource HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn

{
  "specversion": "1.0",
  "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
  "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
  "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
   ... further attributes omitted ...
  "data": {
        ... application data ...
  }
}

Batched content mode: HTTP POST request with two JSON event format encoded events:

[
    {
        "specversion": "1.0",
        "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
        "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
        "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
        ... further attributes omitted ...
        "data": {
                ... application data ...
        }
    },
    {
        "specversion": "1.0",
        "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
        "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
        "id": "1ca55552-bc4a-4f5d-8cc8-8106e3e883c1",
        ... further attributes omitted ...
        "data": {
                ... application data ...
        }
    }
]

Binary content mode: HTTP POST request with context attributes mapped to HTTP-headers:

POST /myresource HTTP/1.1
Host: webhook.example.com
ce-specversion: 1.0
ce-type: nl.overheid.zaken.zaakstatus-gewijzigd
ce-id: f3dce042-cd6e-4977-844d-05be8dce7cea
ce-source: urn:nld:oin:00000001823288444000:systeem:BRP-component
... further attributes omitted ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
    ... application data ...
}

• HTTP Protocol Binding for CloudEvents - Version 1.0.1

• Each CloudEvents event can be wholly represented as a JSON object and MUST use the media type application/cloudevents+json.
• The CloudEvents JSONSchema for the spec can be used to validate events in JSON.
• Unset attributes MAY be encoded to the JSON value of null. When decoding attributes and a null value is encountered, it MUST be treated as the equivalent of unset or omitted. OPTIONAL not omitted attributes MAY be represented as a null JSON value.
• The runtime data type of the `data' content inside the JSON object can be either:
  • a textual JSON value with member name data
  • a binary JSON string expression containing the Base64 encoded binary value with member name data_base64
• So if a data_base64 member is present it indicates that its value is Base64 encoded binary data.
• JSON Batch Format can be used to batch several CloudEvents into a single JSON document.
  • The document contains a JSON array filled with CloudEvents in the JSON Event format.
  • Media type application/cloudevents-batch+json MUST be used.
  • The JSON Batch Format MUST NOT be used when only support for the JSON Format is indicated.

• One SHOULD use the JSON Event Format for CloudEvents.
• There are no agreements to deviate from the standard in any part.
• If applicable then one SHOULD use JSON as primary event format:
  • JSON is the only event format that MUST be supported when HTTP structured content mode is used.
  • JSON will be the primary format for APIs as formulated within the API strategie voor de Nederlandse overheid - Extensies.

Event with an attribute 'geheimnummer' having a null value and a 'data' attribute with a JSON value:

{
  "specversion": "1.0",
  "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
  "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
  "subject": "123456789",
  "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
  "time": "2021-12-10T17:31:00Z",
  "nlbrpnationaliteit": "0083",
  "geheimnummer": null,
  "dataref": "https://gemeenteX/api/persoon/123456789",
  "sequence": "1234",
  "sequencetype": "integer",
  "datacontenttype": "application/json",
  "data": {
    "bsn": "1234567789",
    "naam": "Jan Jansen",
    "gecontroleerd": "ja"
  }
}

Event with both the attribute 'datacontenttype' and 'data_base64' and a JSON string expression with Base64 encoded binary data as value of the 'data_base64' attribute:

{
  "specversion": "1.0",
  "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
  "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
  "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
  "datacontenttype": "application/vnd.apache.thrift.binary",
  "data_base64": "YWFwIG5vb3QgbWllcw=="
}

Event with only the attribute 'data_base64' and a JSON string expression with Base64 encoded binary data as value of the 'data_base64' attribute:

{
  "specversion": "1.0",
  "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
  "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
  "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
  "data_base64" : "YWFwIG5vb3QgbWllcw=="
}

• JSON Event Format for CloudEvents - Version 1.0.1

The 'HTTP 1.1 Web Hooks for Event Delivery' specification prescribes rules constraining the use and handling of specific HTTP methods and headers and defines:

1. a HTTP method by how notifications are delivered by the sender
2. an authorization model for event delivery to protect the delivery target
3. a registration handshake that protects the sender from being abused for flooding arbitrary HTTP sites with requests. For each of the mechanisms it is described which agreements apply to both sender and receiver. The specification

• One SHOULD use the HTTP 1.1 Web Hooks for Event Delivery.
• There are no agreements to deviate from the standard in any part.
• As described in the specification usage of an access token added to the HTTP Request URI Query component has a number of security weaknesses and therefore SHOULD NOT be used unless it is impossible to send an access token in the Authorization request header field.
• The CloudEvents specification focuses on automated validation of intended notification applications. Within the context of the Dutch government, there can (also) be non-automated validation (e.g. by specifying endpoints in agreements between the organizations involved). In those cases it is not always necessary to perform an automated handshake before notifications may be sent.
• An automated handshake as described can take place at different moments. If automated subscription to event notification is used:
  • one SHOULD perform a handshake as described in the specification immediately at registration time
  • one MAY perform a handshake as a "pre-flight" request immediately preceding a delivery.

Validation request:

OPTIONS /endpoint HTTP/1.1
Host: webhook.example.com
WebHook-Request-Origin: eventemitter.example.com
WebHook-Request-Callback: https://example.com/confirm?id=12345&key=...base64..
WebHook-Request-Rate: 120

Validation response:

HTTP/1.1 200 OK
Allow: GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS
Access-Control-Allow-Origin: https://eventemitter.example.com
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS
Access-Control-Allow-Headers: Content-Type 
WebHook-Allowed-Origin: eventemitter.example.com
WebHook-Allowed-Rate: 120

Delivery request:

• HTTP structured content mode with a
• JSON event format encoded event with a
• OAuth 2.0 Bearer token

POST /myresource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM
WebHook-Request-Origin: eventemitter.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn

{
  "specversion": "1.0",
  "type": "nl.overheid.zaken.zaakstatus-gewijzigd",
  "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component",
  "id": "f3dce042-cd6e-4977-844d-05be8dce7cea",
   ... further attributes omitted ...
}

Delivery response:

HTTP/1.1 204 No Content

• HTTP 1.1 Web Hooks for Event Delivery - Version 1.0.1