Skip to main content

Overview

Gmail lets agents and workflows search, read, draft, send, and label emails. On Langdock Cloud, members can connect Gmail with the Langdock OAuth client, and no setup is needed. Follow this guide if you use your own Google OAuth client, for example on a dedicated deployment or to show your own branding on the consent screen. It has two parts:
  1. Create a Google OAuth client so members can connect Gmail.
  2. Set up webhook triggers (optional).
Authentication: OAuth Category: Communication Availability: All workspace plans

Prerequisites

  • A Google Cloud project you can manage
  • Admin access to your Langdock workspace
  • For webhook triggers: permission to create Pub/Sub topics, subscriptions, and service accounts in that project

Create a Google OAuth client

1

Enable the Gmail API

In the Google Cloud console, select your project, open APIs & Services → Library, and enable the Gmail API.
2

Configure the consent screen

Open Google Auth Platform and complete Branding. Under Audience, choose Internal if only users of your Google Workspace organization connect. Gmail scopes are restricted, so an External app needs Google’s verification before users outside your test users can connect.Under Data access, add the scopes listed in Permissions.
3

Create the OAuth client

Open Google Auth Platform → Clients and click Create client. Choose Web application as the application type.Under Authorized redirect URIs, add the Redirect URL from Langdock. To find it, go to Workspace settings → Integrations, select Gmail, and open the OAuth client dialog under Bring your own OAuth Client.
The redirect URL must match exactly. Any mismatch causes redirect_uri_mismatch errors during authentication.
Click Create and copy the Client ID and Client secret.
4

Add the client in Langdock

In the Gmail OAuth client dialog, enter the Client ID and Client secret, choose who can use the client under Access, then click Save and confirm. Select the saved client from the client list and confirm the switch to activate it.For details on access options and group clients, see Bring Your Own OAuth Client.
5

Test the connection

Have a user connect their Gmail account and run a Gmail action, such as Search emails.

Set up webhook triggers

Gmail has two kinds of triggers:
  • Polling triggers (New email, New email matching search, Label changed on email) check for changes on a schedule. They work with any OAuth client.
  • Webhook triggers (Monitor inbox, Monitor labels, Monitor sent emails) start workflows within seconds. Gmail sends change notifications through Google Cloud Pub/Sub, so your OAuth client needs a Pub/Sub topic and push subscription.
Without this setup, the webhook triggers fail to turn on. Polling triggers and actions keep working.
The topic must be in your OAuth client’s Google Cloud project, and Google must be able to reach your Langdock instance. Dedicated deployments need integration webhook triggers enabled.
1

Enable the Cloud Pub/Sub API

In the Google Cloud console, open the project of your OAuth client, go to APIs & Services → Library, and enable the Cloud Pub/Sub API.
2

Create a Pub/Sub topic

  1. Open Pub/Sub → Topics and click Create topic.
  2. Enter a topic ID, such as gmail-webhooks, clear Add a default subscription, and click Create.
  3. On the topic page, click Show info panel in the top right. In the Permissions tab, click Add principal.
  4. Enter gmail-api-push@system.gserviceaccount.com, select the Pub/Sub Publisher role, and click Save.
Gmail uses this account to publish change notifications to your topic.
3

Create a push service account

  1. Open IAM & Admin → Service accounts and click Create service account.
  2. Enter a name, such as gmail-pubsub-push, and click Create and continue.
  3. Skip Permissions and Principals with access and click Done. The account needs no roles, because Pub/Sub only uses it to sign the requests it sends to Langdock.
  4. Copy the service account email from the list. You need it in the next steps.
To select this account in the push subscription, you need the Service Account User role on it. Project owners and editors already have it.
4

Save the topic and service account in Langdock

  1. In the Gmail OAuth client dialog, expand Webhook triggers.
  2. In Pub/Sub topic, enter the full topic path, such as projects/PROJECT_ID/topics/gmail-webhooks.
  3. In Push subscription service account, enter the service account email, such as gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com.
  4. Click Save and confirm.
  5. Copy the push endpoint that now appears in the dialog.
5

Create a push subscription

Open your topic in Pub/Sub → Topics and click Create subscription:
  • Delivery type: Push
  • Endpoint URL: the push endpoint from Langdock
  • Enable authentication: on, with the service account from step 3
  • Audience: leave empty
  • Retry policy: Retry after exponential backoff delay
  • Expiration period: Never expire
Leave Audience empty. Pub/Sub then uses the endpoint URL as the audience, which is what Langdock checks. Langdock rejects requests with any other audience.
Keep the other defaults and click Create.
With the default expiration, Google deletes the subscription after 31 days without notifications, and webhook triggers stop without an error.
6

Test a webhook trigger

Create a workflow with an Integration Trigger, choose Gmail and Monitor inbox, and send yourself an email. The workflow starts within seconds.

How it works

Gmail allows one notification channel per mailbox and publishes every change to your topic. A notification only contains the mailbox address and a change marker, never email content. Pub/Sub pushes it to Langdock, signed by your service account. Langdock checks the signature and endpoint, then each subscribed trigger fetches the changes with its own Gmail connection. A trigger only ever sees emails that its connection can read. You only need one topic, service account, and push subscription per OAuth client. If you have several Google OAuth clients, each one shows its own push endpoint and needs its own push subscription, but they can share one topic and service account if they are in the same project.

Permissions

Add these scopes to your consent screen. Langdock requests the scopes needed by the actions enabled in your workspace. Learn more in Manage Action-Level Scopes.

Troubleshooting

Check that the Webhook triggers section of the OAuth client has both the topic and the service account, and that the connection was created with that OAuth client. Connections keep the client they were created with.Also check that the topic is in the same Google Cloud project as the OAuth client and that gmail-api-push@system.gserviceaccount.com has the Pub/Sub Publisher role on it.
Open the push subscription in the Google Cloud console and check the response codes under Metrics → Push:
  • 401: the subscription has authentication turned off, uses a different service account than the one saved in Langdock, or has an Audience set.
  • 403: a firewall, WAF, or proxy in front of Langdock blocks Google’s requests. Allow POST requests to /api/webhook-pubsub/. Langdock verifies each request’s signature itself.
  • 404: the endpoint URL does not match the push endpoint shown in Langdock, or the OAuth client has no webhook trigger settings.