Detecting Firestore Changes and Triggering Cloud Run via Eventarc
Detecting Firestore Changes and Triggering Cloud Run via Eventarc
Date: May 2026
Overview
This document explains how to detect changes in Firestore data and use them to trigger a Cloud Run service using Google Cloud Eventarc.
Architecture
Firestore document change
│
▼
Eventarc Trigger
(written/created/updated/deleted)
│
▼
Cloud Run Service
(receives CloudEvents HTTP POST)
Alternatively, if fan-out or buffering is needed (matching the existing pattern in this repo):
Firestore document change
│
▼
Eventarc Trigger
│
▼
Pub/Sub Topic
│
▼
Cloud Run (Push Subscription)
Option 1: Eventarc → Cloud Run (Recommended)
Eventarc natively listens to Firestore document change events and routes them directly to a Cloud Run service.
gcloud CLI example
gcloud eventarc triggers create firestore-trigger \
--location=europe-west1 \
--destination-run-service=your-cloud-run-service \
--destination-run-region=europe-west1 \
--event-filters="type=google.cloud.firestore.document.v1.written" \
--event-filters="database=(default)" \
--event-filters-path-pattern="document=your-collection/{document}" \
--service-account=your-sa@project.iam.gserviceaccount.com
Terraform example
# Grant the service account the Eventarc receiver role
resource "google_project_iam_member" "sa_eventarc_receiver" {
project = var.project
role = "roles/eventarc.eventReceiver"
member = "serviceAccount:${google_service_account.service_account.email}"
}
# Grant Firestore permission to publish to Eventarc
resource "google_project_iam_member" "firestore_eventarc_publisher" {
project = var.project
role = "roles/eventarc.publisher"
member = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-firestore.iam.gserviceaccount.com"
}
# Eventarc trigger: Firestore document write → Cloud Run
resource "google_eventarc_trigger" "firestore_change_trigger" {
name = "${var.component}-firestore-trigger"
project = var.project
location = var.region
matching_criteria {
attribute = "type"
value = "google.cloud.firestore.document.v1.written"
}
matching_criteria {
attribute = "database"
value = "(default)"
}
matching_criteria {
attribute = "document"
value = "your-collection/{document}"
operator = "match-path-pattern" # required for wildcard paths
}
destination {
cloud_run_service {
service = google_cloud_run_v2_service.service_queuer.name
region = var.region
path = "/firestore-event" # endpoint on your Cloud Run service
}
}
service_account = google_service_account.service_account.email
labels = {
env = var.env
}
}
Option 2: Eventarc → Pub/Sub → Cloud Run
Use this when you need fan-out (multiple consumers) or want to reuse the existing Pub/Sub subscriber pattern already present in this repo.
# Eventarc trigger routes Firestore events to a Pub/Sub topic
resource "google_eventarc_trigger" "firestore_pubsub_trigger" {
name = "${var.component}-firestore-pubsub-trigger"
project = var.project
location = var.region
matching_criteria {
attribute = "type"
value = "google.cloud.firestore.document.v1.written"
}
matching_criteria {
attribute = "database"
value = "(default)"
}
matching_criteria {
attribute = "document"
value = "your-collection/{document}"
operator = "match-path-pattern"
}
destination {
cloud_run_service {
service = google_cloud_run_v2_service.service_queuer.name
region = var.region
path = "/enqueue"
}
}
service_account = google_service_account.service_account.email
}
Firestore Event Types
| Event Type | Fires When |
|---|---|
google.cloud.firestore.document.v1.written |
Document created, updated, or deleted |
google.cloud.firestore.document.v1.created |
New document created only |
google.cloud.firestore.document.v1.updated |
Existing document changed |
google.cloud.firestore.document.v1.deleted |
Document deleted |
CloudEvents Payload
Your Cloud Run service receives an HTTP POST with a Content-Type: application/cloudevents+json header. The body:
{
"specversion": "1.0",
"type": "google.cloud.firestore.document.v1.written",
"source": "//firestore.googleapis.com/projects/my-project/databases/(default)",
"subject": "documents/your-collection/doc-id",
"id": "unique-event-id",
"time": "2026-05-12T10:00:00Z",
"datacontenttype": "application/json",
"data": {
"oldValue": {
"name": "projects/my-project/databases/(default)/documents/your-collection/doc-id",
"fields": { "status": { "stringValue": "pending" } }
},
"value": {
"name": "projects/my-project/databases/(default)/documents/your-collection/doc-id",
"fields": { "status": { "stringValue": "processed" } }
},
"updateMask": {
"fieldPaths": ["status"]
}
}
}
oldValue— state before the change (nullon create)value— state after the change (nullon delete)updateMask.fieldPaths— list of fields that changed (only present on update)
Go Handler Example (Cloud Run)
package main
import (
"encoding/json"
"io"
"log"
"net/http"
)
type FirestoreEvent struct {
OldValue map[string]interface{} `json:"oldValue"`
Value map[string]interface{} `json:"value"`
UpdateMask struct {
FieldPaths []string `json:"fieldPaths"`
} `json:"updateMask"`
}
func firestoreEventHandler(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "failed to read body", http.StatusBadRequest)
return
}
// CloudEvents wraps the Firestore payload in the "data" field
var envelope struct {
Data FirestoreEvent `json:"data"`
}
if err := json.Unmarshal(body, &envelope); err != nil {
http.Error(w, "failed to parse event", http.StatusBadRequest)
return
}
event := envelope.Data
log.Printf("changed fields: %v", event.UpdateMask.FieldPaths)
log.Printf("new value: %v", event.Value)
// Your business logic here
w.WriteHeader(http.StatusOK)
}
Required IAM Roles
| Principal | Role | Purpose |
|---|---|---|
| Cloud Run service account | roles/eventarc.eventReceiver |
Receive Eventarc events |
Firestore service account (gcp-sa-firestore.iam.gserviceaccount.com) |
roles/eventarc.publisher |
Publish change events to Eventarc |
| Cloud Run service account | roles/run.invoker |
Allow Eventarc to invoke the Cloud Run service |
Prerequisites
- Google provider
>= 4.50forgoogle_eventarc_triggerwith Firestore support - Firestore must be in Native mode (not Datastore mode)
- Eventarc API must be enabled:
gcloud services enable eventarc.googleapis.com