Skip to content
PuglieseWeb Engineering HandbookSystemDox Pages

CloudEvents

CloudEvents is a vendor-neutral specification for describing event data in a common way, so that a broker, a router or an integration can understand a message without knowing the business logic behind it. It began in the CNCF Serverless Working Group in 2017 and graduated as a CNCF project in 2024. The current release of the core specification is v1.0.2.

An event carries a small set of required context attributes — id, source, specversion, type — plus optional ones such as time, subject and datacontenttype, and then the event data itself.

Two transport modes

Section titled “Two transport modes”

The specification defines two ways of putting a CloudEvent onto a transport:

  1. Structured mode. The whole event, attributes and data together, is encoded — typically as JSON — in the message body, with the content type set to identify it, for example application/cloudevents+json. The event survives being forwarded across transports unchanged, which makes it the safer choice at a system boundary.
  2. Binary mode. The context attributes are mapped to the transport’s own metadata — headers, properties — and the data alone occupies the message body. Metadata can then be read for routing and filtering without parsing the payload, and the payload is not double-encoded.

Binary mode suits a broker whose native metadata model is a good fit, and its trade-offs are practical rather than conceptual: transports differ in header size limits and in how header values must be encoded, and each protocol binding needs its own serialisation.

Protocol bindings

Section titled “Protocol bindings”

The specification publishes protocol bindings for HTTP, AMQP, Kafka, MQTT and NATS; a WebSockets binding exists only as a working draft. Where a binding exists, use it rather than inventing a header convention.

  • Kafka — context attributes become record headers prefixed ce_; data goes in the record value. Worked example on that page.
  • AMQP / RabbitMQ — context attributes become AMQP application properties, prefixed cloudEvents:; data goes in the message body.

Where there is no binding: EventBridge

Section titled “Where there is no binding: EventBridge”

Amazon EventBridge has no CloudEvents protocol binding, and it has no message-attribute mechanism of the kind SNS and SQS provide. Its native envelope is its own format, with top-level fields including version, id, detail-type, source, account, time, region, resources and detail.

Two options follow, and both are conventions a team adopts rather than features AWS provides:

  • Carry a structured-mode CloudEvent inside detail, so producers and consumers agree on the CloudEvent envelope and EventBridge sees only an opaque payload it can still pattern-match on.
  • Reshape the event on the way out with a rule input transformer, which lets an input template build a CloudEvent-shaped JSON body for a target such as an API destination.

The mapping is not lossless in either direction, and detail-type and source are not interchangeable with type and source without a stated convention, so write the convention down rather than leaving it implied.

Further reading

Section titled “Further reading”