Event Envelope

Event Streaming Platforms allow many different types of applications to work together. An Event Envelope provides a standard set of well-known fields across all Events sent through the Event Streaming Applications. The envelope is independent of the underlying event format, and often references attributes such as the encryption type, schema, key, and serialization format. Envelopes are analogous to protocol headers in networking (for example, TCP-IP).

Problem

How can I convey information to all participants in an Event Streaming Platform independently of the event payload? For example, how can I convey how to decrypt an Event, what schema is used, or what ID defines the uniqueness of the event?

Solution

Use an Event Envelope to wrap the event data using a standard format agreed on by all participants of the Event Streaming Platform, or more broadly. Cloud Events—which standardize access to ID, Schema, Key, and other common event attributes—are an industry-standard example of the Event Envelope pattern.

Example Implementation

Using basic Java consumers and producers, you can use a helper function to wrap an application's immutable payload into an envelope which conforms to the expected format of the Event Streaming Platform:

static <T> Envelope<T> wrap(T payload, Iterable<Header> headers) {
	return new Envelope(serializer(payload), headers);
}
static <T> T unwrap(Envelope<T> envelope) {
	return envelope.payload;
}

References

• This pattern is derived from Envelope Wrapper in Enterprise Integration Patterns, by Gregor Hohpe and Bobby Woolf.
• How to Choose Between Strict and Dynamic Schemas
• See CloudEvents for a specification that describes event header information in a common way.