Send events to Google Pub/Sub
Topic delivery with ordering keys and dead-letter topics, native to GCP.
What is Google Pub/Sub?
Google Cloud Pub/Sub is GCP's managed messaging service, pull or push subscribers, ordering keys, dead-letter topics, and tight integration with Dataflow and Cloud Functions. Pushrail publishes events to a customer-owned topic; subscribers on the customer side fan out to whatever downstream processing they run.
Why deliver events to Google Pub/Sub
- GCP-native, integrates with Dataflow, Cloud Functions, Cloud Run, and Workflows.
- Ordering keys preserve per-customer or per-resource order.
- Attributes carry envelope fields as headers, so subscribers filter without parsing.
- Dead-letter topics give the customer's subscribers a built-in failure path.
How Pushrail delivers events to Google Pub/Sub
The adapter publishes one message per event to the configured topic. Ordering keys default to `customerExternalId`. Envelope fields (`event_type`, `occurred_at`, `customer_external_id`, `idempotency_key`) are set as message attributes; the canonical JSON event is the message data.
Auth and credentials
Customers authorize Pushrail via Workload Identity Federation (preferred, no key exchanged) or a service-account JSON key with `roles/pubsub.publisher` on the destination topic. Service-account keys are stored encrypted at rest; rotations happen in-place. The principal needs no project-level roles, only the topic-level publisher binding.
Batching, retries, and replay
The publisher batches up to 10 MB or 1,000 messages per request with a 10 ms linger, Pub/Sub recommends large batches for throughput. Transient errors (RESOURCE_EXHAUSTED, UNAVAILABLE) retry with exponential backoff. Permanent errors (PERMISSION_DENIED, NOT_FOUND) land in the DLQ. Replay re-publishes with the same ordering keys, so order is preserved on re-runs.
Example payload
Pushrail accepts the canonical event shape on POST /v1/events. Below is the ingestion request your service makes.
{
"eventType": "order.completed",
"occurredAt": "2026-05-26T14:21:08.493Z",
"source": "billing-service",
"customerExternalId": "acct_8K2zRq",
"idempotencyKey": "order_38a91f-completed",
"correlationId": "req_4f30b2",
"payload": {
"orderId": "ord_38a91f",
"amount": 12900,
"currency": "USD",
"items": [
{ "sku": "PR-PRO-MONTHLY", "qty": 1, "price": 12900 }
]
},
"metadata": {
"tier": "pro",
"region": "us-east-1"
}
}Example configuration
The fields your customer fills in to point Pushrail at their Google Pub/Sub setup.
{
"type": "PUBSUB",
"name": "Customer Pub/Sub topic",
"projectId": "acme-events-prod",
"topic": "pushrail-events",
"orderingKey": "customerExternalId",
"auth": {
"mode": "WORKLOAD_IDENTITY",
"serviceAccountEmail": "pushrail-publisher@acme-prod.iam.gserviceaccount.com"
}
}Common use cases
- GCP-native customers who don't run Kafka but want real-time event delivery.
- Feed Dataflow pipelines on the customer's side.
- Power Cloud Functions or Cloud Run triggers driven by your product events.
- Bridge your product into a customer's GCP-based event-driven architecture.
Related destinations
Native Kafka producer with SASL/TLS, deliver events into a customer's topic with configurable partitioning.
Ordered shard delivery into a customer-owned Kinesis Data Stream, configurable partition keys, native AWS SDK.
Deliver events into a customer's EventBridge bus, rule-driven routing inside AWS.
Frequently asked questions
Do I need to run Kafka to get real-time delivery on GCP?
No. The Pub/Sub adapter publishes one message per event to a customer-owned topic, and their subscribers fan out to whatever downstream processing they run: Dataflow, Cloud Functions, Cloud Run, or Workflows.
How is ordering preserved?
Ordering keys default to customerExternalId, so per-customer or per-resource order is preserved. Envelope fields are set as message attributes so subscribers can filter without parsing the payload. Replay re-publishes with the same ordering keys.
Whose credentials are used to publish?
The customer's. They authorize Pushrail via Workload Identity Federation (preferred, no key exchanged) or a service-account JSON key with roles/pubsub.publisher on the destination topic. Keys are stored encrypted at rest and the principal needs only the topic-level publisher binding.
What happens if a publish fails?
Transient errors (RESOURCE_EXHAUSTED, UNAVAILABLE) retry with exponential backoff; permanent errors (PERMISSION_DENIED, NOT_FOUND) land in the dead-letter queue. Customers can also attach Pub/Sub dead-letter topics for a subscriber-side failure path.