CloudEvents format - HTTP protocol binding

Advanced Standard

CloudEvents (cloudevents.io) is a specification for describing event data in a common way. The specification is under the Cloud Native Computing Foundation (CNCF) and is organized by the CNCF's Serverless Working Group.

Eventarc delivers events to the event receiver in the CloudEvents format through an HTTP request.

Note: As the Eventarc product evolves, we might apply backwards-compatible changes, like adding optional filtering attributes, output-only attributes, or optional fields to the event payload.

HTTP request headers

Target services receive events from event routers as HTTP POST requests formatted to the CloudEvents version 1.0 HTTP protocol binding specification. Each HTTP request contains event-specific headers and a body, and is sent to the root URL path (/) of the service.

In addition to other HTTP headers, all events have the following CloudEvents HTTP headers:

Header	Description	Example
ce-id	Unique identifier for the event	1096434104173400
ce-source	Identifies the source of the event	//pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion	The CloudEvents specification version used for this event	1.0
ce-type	The type of event data	google.cloud.pubsub.topic.v1.messagePublished
ce-time	Event generation time, in RFC 3339 format (optional)	2020-12-20T13:37:33.647Z

HTTP payload format

Cloud Audit Logs

Events of type google.cloud.audit.log.v1.written have the following format:

Headers

ce-specversion: 1.0
ce-type: google.cloud.audit.log.v1.written
ce-source: //SERVICE_NAME/projects/PROJECT_ID
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH

• SERVICE_NAME: the Google API URI for the service issuing the event; for example, bigquery.googleapis.com for events from BigQuery.
• PROJECT_ID: your Google Cloud project ID.
• MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: system-generated.

Body

The payload is a JSON object detailing the Cloud Audit Logs event. In protoPayload you can find the resourceName, serviceName, and methodName values. For more information, see Determine event filters for Cloud Audit Logs.

Pub/Sub

Events of type google.cloud.pubsub.topic.v1.messagePublished have the following format:

Headers

ce-specversion: 1.0
ce-type: google.cloud.pubsub.topic.v1.messagePublished
ce-source: //pubsub.googleapis.com/TOPIC
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH

• TOPIC: the Pub/Sub topic the event was published to.
• MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: system-generated.

Body

The payload is a Pub/Sub push message. In the data field you can find the message as a Base64-encoded string. See the example in this document.

Open source repository

The structure of the HTTP body for all events are available on the CloudEvents GitHub repository.

The repository contains the following to help you understand and use CloudEvents data in your programming language:

• Google Protocol Buffers for CloudEvents data payloads
• Generated JSON schemas
• A public JSON schema catalog

Links to client libraries are also included.

Common events

Protocol Buffers (or protobufs) represent the data within events that are generated by Eventarc. Protocol Buffers for CloudEvents are provided as machine-readable schemas, allowing libraries of data types to be created and making it easier to consume events.

There are two protobuf messages that are relevant for any given CloudEvent type:

• The envelope message that represents the complete CloudEvent, including any extension attributes; for example, AuditLogWrittenEvent.
• The data message; for example, LogEntryData or StorageObjectData.

Many CloudEvent types can use the same data message. For example, every event associated with a Cloud Storage object uses StorageObjectData as the data message. Each envelope message specifies the CloudEvent type that it is associated with through a proto annotation. For more information, see Relationship between protobuf messages and CloudEvent types.

The following tables detail the components of some common events:

Cloud Audit Logs

Proto files	google/events/cloud/audit/v1/events.proto google/events/cloud/audit/v1/data.proto
Envelope message	google.events.cloud.audit.v1.AuditLogWrittenEvent
Data message	google.events.cloud.audit.v1.LogEntryData
Event type (when an audit log entry is written)	google.cloud.audit.log.v1.written
Event extensions	serviceName methodName resourceName See the list of event types using Cloud Audit Logs.
Examples	Pub/Sub audit log BigQuery audit log
More information	Create an Eventarc trigger for a Cloud Audit Logs event Determine event filters for Cloud Audit Logs Google Cloud services with audit logs

Cloud Storage

Proto files	google/events/cloud/storage/v1/events.proto google/events/cloud/storage/v1/data.proto
Envelope messages	google.events.cloud.storage.v1.ObjectFinalizedEvent google.events.cloud.storage.v1.ObjectArchivedEvent google.events.cloud.storage.v1.ObjectDeletedEvent google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Data message	google.events.cloud.storage.v1.StorageObjectData
Resource	Objects
Event types	See the list of direct event types.
Examples	Simple Complex
More information	Create an Eventarc trigger for a Cloud Storage event Receive events from Cloud Storage in a Cloud Run service

Firestore

Proto files	google/events/cloud/firestore/v1/events.proto google/events/cloud/firestore/v1/data.proto
Envelope messages	google.events.cloud.firestore.v1.DocumentCreatedEvent google.events.cloud.firestore.v1.DocumentUpdatedEvent google.events.cloud.firestore.v1.DocumentDeletedEvent google.events.cloud.firestore.v1.DocumentWrittenEvent
Data message	google.events.cloud.firestore.v1.DocumentEventData
Resource	Document
Event types	See the list of direct event types.
Examples	Simple Complex
More information	Create an Eventarc trigger for a Firestore event Create event-driven architectures with Eventarc and Firestore Extend with Cloud Run functions to handle events triggered by changes in Firestore

Pub/Sub

Proto files	google/events/cloud/pubsub/v1/events.proto google/events/cloud/pubsub/v1/data.proto
Envelope message	google.events.cloud.pubsub.v1.MessagePublishedEvent
Data message	google.events.cloud.pubsub.v1.MessagePublishedData
Resource	PubsubMessage
Event type (when a Pub/Sub message is published)	google.cloud.pubsub.topic.v1.messagePublished
Example	Text
More information	Receive events in a Cloud Run service using Pub/Sub messages Trigger a workflow using Pub/Sub messages

What's next

Learn more about event routes.