CloudEvents ([cloudevents.io](http://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]
> **Note:** As the Eventarc product evolves, we might apply [backwards-compatible](https://docs.cloud.google.com/apis/design/compatibility) 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](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md). 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](https://tools.ietf.org/html/rfc3339) format (optional) | `2020-12-20T13:37:33.647Z` |

<br />

## 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](https://docs.cloud.google.com/eventarc/docs/determining-filters-cal.md.txt).

### 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. For an example, in this
document, see [Common events](https://docs.cloud.google.com/eventarc/docs/cloudevents.md.txt#common-events).


## Open source repository

The structure of the HTTP body for all events are available on the
[CloudEvents GitHub repository](https://github.com/googleapis/google-cloudevents).


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.

<br />


## 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](https://github.com/googleapis/google-cloudevents/blob/main/proto/README.md#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](https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/audit/v1/events.proto) [google/events/cloud/audit/v1/data.proto](https://github.com/googleapis/google-cloudevents/blob/main/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](https://docs.cloud.google.com/eventarc/docs/event-types.md.txt#using-cloud-audit-logs). |
| Examples | [Pub/Sub audit log](https://googleapis.github.io/google-cloudevents/examples/binary/audit/LogEntryData-pubsubCreateTopic.json) [BigQuery audit log](https://googleapis.github.io/google-cloudevents/examples/structured/audit/LogEntryData-bigqueryjobcompleted.json) |
| More information | [Create an Eventarc trigger for a Cloud Audit Logs event](https://docs.cloud.google.com/eventarc/docs/event-providers-targets.md.txt#triggers) [Determine event filters for Cloud Audit Logs](https://docs.cloud.google.com/eventarc/docs/determining-filters-cal.md.txt) [Google Cloud services with audit logs](https://docs.cloud.google.com/logging/docs/audit/services.md.txt) |

### Cloud Storage

|---|---|
| Proto files | [google/events/cloud/storage/v1/events.proto](https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/storage/v1/events.proto) [google/events/cloud/storage/v1/data.proto](https://github.com/googleapis/google-cloudevents/blob/main/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`](https://docs.cloud.google.com/storage/docs/json_api/v1/objects.md.txt) |
| Event types | See the list of [direct event types](https://docs.cloud.google.com/eventarc/docs/event-types.md.txt#cloud-storage). |
| Examples | [Simple](https://googleapis.github.io/google-cloudevents/examples/binary/storage/StorageObjectData-simple.json) [Complex](https://googleapis.github.io/google-cloudevents/examples/binary/storage/StorageObjectData-complex.json) |
| More information | [Create an Eventarc trigger for a Cloud Storage event](https://docs.cloud.google.com/eventarc/docs/event-providers-targets.md.txt#triggers) [Receive events from Cloud Storage in a Cloud Run service](https://docs.cloud.google.com/eventarc/standard/docs/run/create-trigger-storage-console.md.txt) |

### Firestore

|---|---|
| Proto files | [google/events/cloud/firestore/v1/events.proto](https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/firestore/v1/events.proto) [google/events/cloud/firestore/v1/data.proto](https://github.com/googleapis/google-cloudevents/blob/main/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`](https://docs.cloud.google.com/firestore/docs/reference/rest/v1/projects.databases.documents.md.txt) |
| Event types | See the list of [direct event types](https://docs.cloud.google.com/eventarc/docs/event-types.md.txt#cloud-firestore). |
| Examples | [Simple](https://googleapis.github.io/google-cloudevents/examples/binary/firestore/DocumentEventData-simple.json) [Complex](https://googleapis.github.io/google-cloudevents/examples/binary/firestore/DocumentEventData-complex.json) |
| More information | [Create an Eventarc trigger for a Firestore event](https://docs.cloud.google.com/eventarc/docs/event-providers-targets.md.txt#triggers) [Create event-driven architectures with Eventarc and Firestore](https://docs.cloud.google.com/firestore/docs/eventarc) [Extend with Cloud Run functions to handle events triggered by changes in Firestore](https://docs.cloud.google.com/firestore/docs/extend-with-functions-2nd-gen) |

### Pub/Sub

|---|---|
| Proto files | [google/events/cloud/pubsub/v1/events.proto](https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/pubsub/v1/events.proto) [google/events/cloud/pubsub/v1/data.proto](https://github.com/googleapis/google-cloudevents/blob/main/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`](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage.md.txt) |
| Event type (when a Pub/Sub message is published) | `google.cloud.pubsub.topic.v1.messagePublished` |
| Example | [Text](https://googleapis.github.io/google-cloudevents/examples/binary/pubsub/MessagePublishedData-complex.json) |
| More information | [Receive events in a Cloud Run service using Pub/Sub messages](https://docs.cloud.google.com/eventarc/standard/docs/run/create-trigger-pub-sub-gcloud.md.txt) [Trigger a workflow using Pub/Sub messages](https://docs.cloud.google.com/eventarc/standard/docs/workflows/quickstart-pubsub.md.txt) |

<br />

## What's next

[Learn more about event routes](https://docs.cloud.google.com/eventarc/standard/docs/run/event-routing-options.md.txt).