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:- Create a Google OAuth client so members can connect Gmail.
- 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.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.
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
- Open Pub/Sub → Topics and click Create topic.
- Enter a topic ID, such as
gmail-webhooks, clear Add a default subscription, and click Create. - On the topic page, click Show info panel in the top right. In the Permissions tab, click Add principal.
- Enter
gmail-api-push@system.gserviceaccount.com, select the Pub/Sub Publisher role, and click Save.
3
Create a push service account
- Open IAM & Admin → Service accounts and click Create service account.
- Enter a name, such as
gmail-pubsub-push, and click Create and continue. - 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.
- Copy the service account email from the list. You need it in the next steps.
4
Save the topic and service account in Langdock
- In the Gmail OAuth client dialog, expand Webhook triggers.
- In Pub/Sub topic, enter the full topic path, such as
projects/PROJECT_ID/topics/gmail-webhooks. - In Push subscription service account, enter the service account email, such as
gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com. - Click Save and confirm.
- 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
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
A webhook trigger fails to turn on
A webhook trigger fails to turn on
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.The trigger turns on but workflows never start
The trigger turns on but workflows never start
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. AllowPOSTrequests 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.