How to setup webhooks with Gmail on Nango

Learn how to set up Gmail webhooks with Google Pub/Sub and Nango

This guide shows you how to receive real-time Gmail webhooks in Nango using Google Pub/Sub.

How it works

Gmail uses Google Cloud Pub/Sub to deliver push notifications. The flow is:

1. You create a Pub/Sub topic and subscription pointing to your Nango webhook URL
2. You call Gmail’s watch endpoint for each connection to start receiving notifications
3. When a user’s mailbox changes, Google publishes a notification to your topic
4. The Pub/Sub subscription pushes it to Nango
5. Nango matches the notification to the correct connection and forwards it to your app

Nango automatically identifies which connection a webhook belongs to using the emailAddress from the notification payload. For new connections, Nango persists only a hash of the user’s email (connection_config.emailAddressHash) automatically at connection time — no manual setup required.

Setup

1. Create a Pub/Sub topic

Create a topic in the Google Cloud Console. You can use the default options Google sets. See Google’s documentation for details.

2. Grant Gmail publish rights

Gmail needs permission to publish to your topic. You can do this in the Google Cloud Console or with the gcloud CLI.

Option A — Google Cloud Console:

1. Open Pub/Sub Topics in the Google Cloud Console.
2. Click on your topic, then go to the Permissions tab.
3. Click Add principal. Set the principal to [e-mail] and assign the Pub/Sub Publisher role.

Option B — gcloud CLI:

gcloud pubsub topics add-iam-policy-binding <TOPIC_ID> \
  --project=<GOOGLE_PROJECT_ID> \
  --member="serviceAccount:[e-mail]" \
  --role="roles/pubsub.publisher"

The topic ID is the short name (e.g. my-gmail-topic), while the topic name is the fully qualified path (e.g. projects/my-project/topics/my-gmail-topic). You’ll need the topic name later when calling the watch endpoint.

3. Create a push subscription

Click on the default subscription for your topic (if one was created) or create a new one. Select Edit and configure it as follows:

1. Delivery type: Set as push
2. Endpoint URL: Copy the webhook URL from your Gmail integration page in the Nango dashboard, under the Webhook URL section.
3. Authentication (recommended): Enable authentication and configure a service account for added security.
4. Save the changes

4. Activate the watch subscription

Call Gmail’s users.watch endpoint for each connection you want to receive notifications for:

curl -X POST "https://www.googleapis.com/gmail/v1/users/me/watch" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "topicName": "projects/<PROJECT_ID>/topics/<TOPIC_ID>",
    "labelIds": ["INBOX"],
    "labelFilterBehavior": "INCLUDE"
  }'

You can automate this for new connections with a post-connection-creation script:

import { createOnEvent, ProxyConfiguration } from 'nango';

export default createOnEvent({
    event: 'post-connection-creation',
    description: 'Activate the Gmail watch webhook subscription for new connections',
    exec: async (nango) => {
        const config: ProxyConfiguration = {
            baseUrlOverride: 'https://www.googleapis.com/gmail',
            endpoint: '/v1/users/me/watch',
            data: {
                labelIds: ['INBOX'],
                // Replace with your full topic name from the Pub/Sub setup (step 1)
                // Ideally, you should set the value to be read from the Nango env variables (https://nango.dev/docs/reference/functions#environment-variables)
                topicName: 'projects/<PROJECT_ID>/topics/<TOPIC_ID>',
                labelFilterBehavior: 'INCLUDE',
            },
        };

        await nango.post(config);
    }
});

5. Renew the watch subscription daily

Google recommends calling the watch endpoint at least once a day to keep the subscription active. Each call replaces any existing watch for the user, so no separate cleanup is needed. You can use a Nango sync with a 1d frequency for this:

import { createSync, ProxyConfiguration } from 'nango';
import { z } from 'zod';

export default createSync({
    description: 'Calls the watch endpoint daily to keep a Gmail webhook subscription active',
    models: { Empty: z.object({}) },
    endpoints: [{
        method: 'GET',
        path: '/gmail/watch-renewal',
    }],
    syncType: 'full',
    frequency: '1d',
    exec: async (nango) => {
        const config: ProxyConfiguration = {
            baseUrlOverride: 'https://www.googleapis.com/gmail',
            endpoint: '/v1/users/me/watch',
            data: {
                labelIds: ['INBOX'],
                // Replace with your full topic name from the Pub/Sub setup (step 1)
                // Ideally, you should set the value to be read from the Nango env variables (https://nango.dev/docs/reference/functions#environment-variables)
                topicName: 'projects/<PROJECT_ID>/topics/<TOPIC_ID>',
                labelFilterBehavior: 'INCLUDE',
            },
        };

        const response = await nango.post(config);
        await nango.log(response.data);
    }
});

6. Stop the watch subscription on connection deletion

If a connection is deleted in Nango but the Gmail watch remains active, Google may continue sending notifications for that mailbox until the watch expires. To stop notifications immediately for a deleted connection, call Gmail’s users.stop endpoint before deletion.

You can automate this with a pre-connection-deletion lifecycle event:

import { createOnEvent, ProxyConfiguration } from 'nango';

export default createOnEvent({
    event: 'pre-connection-deletion',
    description: 'Stop Gmail watch subscription before connection deletion',
    exec: async (nango) => {
        const config: ProxyConfiguration = {
            baseUrlOverride: 'https://www.googleapis.com/gmail',
            endpoint: '/v1/users/me/stop'
        };

        try {
            await nango.post(config);
        } catch (err) {
            // Avoid blocking connection deletion if stop fails.
            await nango.log(`Failed to stop Gmail watch subscription: ${String(err)}`, { level: 'error' });
        }
    }
});

7. Handle forwarded webhooks

When a Gmail notification arrives, Nango matches it to the correct connection and forwards it to your system. The forwarded payload looks like this:

{
  "from": "google-mail",
  "providerConfigKey": "google-mail",
  "type": "forward",
  "payload": {
    "message": {
      "data": "eyJlbWFpbEFkZHJlc3MiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaGlzdG9yeUlkIjoxMjM0NTY3fQ==",
      "messageId": "15648488012403560",
      "publishTime": "2025-07-21T12:00:31.793Z"
    },
    "subscription": "projects/my-project/subscriptions/my-subscription"
  },
  "connectionId": "connection-123"
}

The message.data field is base64-encoded and contains:

{"emailAddress": "[e-mail]", "historyId": 1234567}

Once you receive the webhook, trigger your existing sync for that connection:

curl -X POST "https://api.nango.dev/sync/trigger" \
  -H "Authorization: Bearer <NANGO_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_mode": "incremental",
    "connection_id": "<CONNECTION_ID>",
    "provider_config_key": "google-mail",
    "syncs": ["emails"]
  }'

With webhooks triggering syncs in real time, you can reduce your sync frequency to a lower value (1d/1h) just to act as a safety net for any missed webhooks.

If you prefer Nango to automatically run a sync when the webhook arrives (instead of forwarding it to your app), you can enable webhook processing in a sync script using webhookSubscriptions and onWebhook. For Gmail, subscribe to '*' and decode payload.message.data to get historyId.

See: Real-time syncs

Connection matching

Nango uses the emailAddress from the webhook payload to find the matching connection (by hashing it internally). The lookup order is:

1. connection_config.emailAddressHash — automatically set by Nango for new connections (created after 2026-03-11)
2. metadata.emailAddress — fallback (customer-controlled)
3. metadata.email — fallback (customer-controlled)

For new connections (created after 2026-03-11), no action is needed. Nango automatically persists the email hash at connection time.

For existing connections created before this feature was available, you have two options:

• Re-authorize the connection so Nango’s post-connection hook runs and persists the email hash automatically
• Set the metadata manually via the API:

curl -X PATCH "https://api.nango.dev/connection/metadata" \
  -H "Authorization: Bearer <NANGO_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<CONNECTION_ID>",
    "provider_config_key": "google-mail",
    "metadata": {"emailAddress": "<USER_EMAIL>"}
  }'

To do this in bulk, iterate over the list connections response and update the metadata for each one.

If Nango cannot match the incoming webhook to a connection (because it can’t find a matching hash/email in connection_config or metadata), the webhook will still be received but won’t include a connectionId in the forwarded payload.

Rollback strategy

If you need to stop webhooks, detach the Pub/Sub subscription from your topic in the Google Cloud Console. This immediately stops notifications from flowing to Nango. The subscription can be re-attached at any time.

Need help getting started? Get help in the community.

---