CloudEvents format

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 your Cloud Run service in the CloudEvents format via an HTTP request.

HTTP request format

Cloud Run 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 GCP 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. Here's an example audit log from Cloud Storage:

{
  "protoPayload": {
    "status": {},
    "authenticationInfo": { ... },
    "requestMetadata": {
      "callerIp": "...",
      "callerSuppliedUserAgent": "...",
      "requestAttributes": {
        "time": "YYYY-MM-DDThh:mm:ss.sZ",
        "auth": {}
      },
      "destinationAttributes": {}
    },
    "serviceName": "storage.googleapis.com",
    "methodName": "storage.objects.create",
    "authorizationInfo": [
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.create",
        "granted": true,
        "resourceAttributes": {}
      },
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.delete",
        "granted": true,
        "resourceAttributes": {}
      }
    ],
    "resourceName": "projects/_/buckets/MY_PROJECT/objects/MY_FILE.txt",
    "serviceData": {
      "policyDelta": {
        "bindingDeltas": [ ... ]
      },
      "@type": "type.googleapis.com/google.iam.v1.logging.AuditData"
    },
    "resourceLocation": {
      "currentLocations": [
        "us-central1"
      ]
    }
  },
  "insertId": "-qklu1af11306y",
  "resource": {
    "type": "gcs_bucket",
    "labels": {
      "location": "us-central1",
      "bucket_name": "MY_BUCKET",
      "project_id": "MY_PROJECT"
    }
  },
  "timestamp": "2021-04-09T17:57:16.718915757Z",
  "severity": "INFO",
  "logName": "projects/MY_PROJECT/logs/cloudaudit.googleapis.com%2Fdata_access",
  "receiveTimestamp": "2021-04-09T17:57:17.748555474Z"
}

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.

{
   "message": {
     "attributes": {
       "key": "value"
     },
     "data": "SGVsbG8gV29ybGQK",
     "messageId": "136969346945",
     "publishTime": "2021-10-02T15:01:23.045123456Z"
   },
   "subscription": "projects/MY_PROJECT/subscriptions/MY_SUBSCRIPTION"
}

Open source

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.