Google Mail Real Time Events - Pub/Sub Setup Guide

🚧
This is a one-time setup per OAuth application. If the OAuth app is already created and a webhook URL has been configured for a Pub/Sub topic in your project, other team members do not need to repeat the steps below.

Step1: Create (or Use) an OAuth Application

Create a Google OAuth application within your Google Cloud project. You can follow the detailed setup guide available here.
If you have already created an OAuth app and successfully set up a Google Mail integration in the Knit dashboard, you do not need to create a new OAuth app.
Instead, proceed with the following steps using the same Google Cloud project where your existing OAuth app is configured.

Step2: Enable Pub/Sub API & Create Topic

To run the following commands, enable Google Clould Shell, It is available on the top right corner of your google console dashboard.
Run this first. This gives Gmail the necessary permissions to talk to your project.

# Set your preferred name
TOPIC_NAME="[[INSERT_YOUR_TOPIC_NAME]]"

# Enable API
gcloud services enable pubsub.googleapis.com

# Create the Topic
gcloud pubsub topics create $TOPIC_NAME

# Grant Gmail permission to publish to this specific topic
gcloud pubsub topics add-iam-policy-binding $TOPIC_NAME \
    --member="serviceAccount:[email protected]" \
    --role="roles/pubsub.publisher"

Step3: Create Service Account

This creates the "Identity" that will sign the requests sent to your future webhook.

# Set your preferred name
SA_NAME="[[INSERT_YOUR_SERVICE_ACCOUNT_NAME]]"
PROJECT_ID=$(gcloud config get-value project)

# Create the account
gcloud iam service-accounts create $SA_NAME --display-name="Gmail Webhook Auth Account"

# Assign Token Creator role so Pub/Sub can use this account to generate Auth headers
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

Step4: Create Subscription and Register Webhook Url

Once you have completed above steps, now hit the subscribe to events endpoint, then in the response, you will get a metaData.masterWebhookUrl use this in place of [[INSERT_YOUR_WEBHOOK_URL]] in the following command.

# Fill these in based on previous steps and your new URL
TOPIC_NAME="[[INSERT_SAME_TOPIC_NAME_FROM_STEP_1]]"
SA_NAME="[[INSERT_SAME_SA_NAME_FROM_STEP_2]]"
SUB_NAME="[[INSERT_NEW_SUBSCRIPTION_NAME]]"
WEBHOOK_URL="[[INSERT_YOUR_WEBHOOK_URL]]"

PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com"

# 1. Create Subscription with Auth and Exponential Backoff
gcloud pubsub subscriptions create $SUB_NAME \
    --topic=$TOPIC_NAME \
    --push-endpoint=$WEBHOOK_URL \
    --push-auth-service-account=$SA_EMAIL \
    --ack-deadline=30 \
    --min-retry-delay=10s \
    --max-retry-delay=600s

📘
A step-by-step Loom walkthrough of the above process (starting from Step 2) is available here: Part 1 and Part 2.

Updated about 12 hours ago