> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google PubSub

> Hightouch and Google PubSub integration

## Overview

Hightouch supports streaming events from Google Pub/Sub in realtime.

Simply configure your Google Pub/Sub source in the Hightouch UI, and Hightouch will automatically extract, transform, and load your data into Hightouch Events. Your data can then be synced to your warehouse or streamed to our catalog of realtime destinations.

## Setup

To get started, [**create an event source**](https://app.hightouch.com/events/sources/new?from=docs), select **Google Pub/Sub** and follow the steps below.

### Configure your source

Configure the following fields in Hightouch:

* **Credentials**: GCP credentials for connecting to Pub/Sub.
* **Subscription**: The full name of the Pub/Sub subscription to consume events from.
* **Project ID**: The Google Cloud Project ID.
* **Regional API Endpoint**: [List of endpoints](https://cloud.google.com/Pub/Sub/docs/reference/service_apis_overview#Pub/Sub_endpoints)

### Grant permissions

Hightouch believes in the principle of least privilege. We ask for no more permissions than necessary. For the Google Pub/Sub event source, Hightouch requires `roles/Pub/Sub.subscriber` and `roles/Pub/Sub.viewer`. Ensure you run the command in your Google Cloud Console to grant Hightouch's service account the correct permissions.

### Message format

Hightouch Events supports PubSub messages encoded using Avro and Protobuf as long as a [PubSub Schema](https://cloud.google.com/pubsub/docs/schemas) is configured and associated with the topic. Otherwise, messages need to be encoded as JSON.

## Event Structure

All events are ingested into Hightouch as `track` events. The Pub/Sub message `id`, `data`, and `attributes` are exposed as custom `properties` on the `track` event. Metadata such as `subscription` are also exposed in the `context.Pub/Sub` object.

For example, the following Pub/Sub message:

```json theme={null}
{
  "id": "123",
  "data": {
    "user_id": "user_123",
    "amount": 123.45
  },
  "attributes": {
    "a1": "abc"
  }
}
```

Will be ingested into Hightouch as:

```json theme={null}
{
  "type": "track",
  "event": "Google Pub/Sub Event",
  "properties": {
    "id": "123",
    "data": {
      "user_id": "user_123",
      "amount": 123.45
    },
    "attributes": {
      "a1": "abc"
    }
  },
  "context": {
    "Pub/Sub": {
      "subscription": "projects/my-project/subscriptions/my-subscription"
    }
  },
  "timestamp": "2024-07-29T14:52:37.648Z"
}
```

### Field mappings

You can configure how Hightouch transforms messages from your Pub/Sub topic to Hightouch [`track` events](https://docs.hightouch.com/events/event-spec#track-events). Mappings can be configured for the following fields:

* `event`
* `userId`
* `anonymousId`
* `messageId`
* `timestamp`

You can also transform your events using Functions in order to standardize the schema or enrich its contents.

### Schema Enforcement

[Event Contracts](https://docs.hightouch.com/events/contracts/management.md) can be attached to Google Pub/Sub sources just like any other Event Source.

## Tips and troubleshooting

If you run into an issue this page doesn't cover, [contact support](#pylon-chat).