Google Workspace integration (Gmail + Chat)¶

Fan Datahub platform signals — task completion, workflow approvals, alert rule fires — into your organisation through Gmail and Google Chat, using one customer-owned service account in your own Google Cloud project.

Each Datahub deployment connects to one service account, delegated by your Workspace administrator to send as specific mailboxes. Datahub never holds credentials for any other tenant.

Auth modelService account · domain-wide delegation

DestinationsGmail · Google Chat

Scopegmail.send only

Dispatch logdelivered · failed · blocked

When to use it¶

Use this integration when your organisation runs on Google Workspace rather than Microsoft 365. Each destination is a channel in Datahub, and you can run both kinds at once.

:material-google-chat:{ .lg .middle } Broadcast to a Chat space

A #data-quality space that should get a card every time an Alerts rule fires or a workflow is rejected.
Route to a mailbox

A steward's inbox, a shared alias, or a ticket-system address that should receive a specific alert — and the only Google channel that can carry a spreadsheet.

Not for per-user notifications

Both channel types are organisation-level destinations. Datahub's own in-app notifications and task inbox already cover "tell this person about their work" — this integration is for pushing a signal into a shared place.

How it works¶

flowchart LR
    SIG["Matched signal<br/>capability on · channel subscribed"] --> DISP(["Google Workspace dispatch"])
    DISP --> CHAT["Chat space<br/>incoming webhook URL"]
    DISP --> GMAIL["Gmail<br/>API sends as From mailbox"]
    CHAT --> LOG
    GMAIL --> LOG
    LOG[("Activity tab<br/>every attempt, with the file it carried")]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class DISP accent

Figure 1 — One dispatcher, two transports. A Chat space is reached with a webhook URL and needs no Google credentials at all; Gmail sends as a real mailbox and is the half that needs the service account.

The trust model¶

Datahub authenticates as a service account you own, which your Workspace administrator explicitly delegates to send mail as named users. Three properties follow, and they are the reason the setup has the shape it does:


You own the credential	The service account lives in your Google Cloud project. Revoking its delegation, or deleting its key, cuts Datahub off immediately and without our involvement.
One scope, not a mailbox	The delegation grants `gmail.send` and nothing else. Datahub cannot read mail, list messages, or touch Drive — the scope does not permit it.
Sending is not reading	`gmail.send` lets Datahub send as a mailbox. It does not let anyone at Datahub, or any AI agent, see what is in it.

Google Chat needs none of this

A Chat webhook URL is self-authenticating: whoever holds it can post to that space. If you only want Chat, skip the service account entirely — create the integration, enable the Chat capability, and paste the URL.

Setup¶

Two consoles, in this order. Steps 1–3 are Google Cloud; steps 4–5 are the Workspace Admin console; step 6 is Datahub.

1. Create the service account¶

In the Google Cloud console, pick or create a project, then IAM & Admin → Service Accounts → Create service account.

Give it a name you will recognise later (datahub-notifications). Grant it no roles — project roles are about Google Cloud resources and have nothing to do with sending mail. The permission that matters is granted in the Admin console, in step 5.

2. Create a JSON key¶

On the service account: Keys → Add key → Create new key → JSON. The file downloads once and cannot be re-downloaded.

That file is a credential

Anyone holding it can send mail as every mailbox you delegate to. Treat it like a password: do not commit it, do not paste it into chat or a ticket. Datahub stores the private key in a secret manager and keeps only a reference to it in the integration config.

3. Copy the client ID¶

On the service account's Details tab, copy the Unique ID — a long number. This is what the Admin console calls the Client ID, and it is not the client_email.

4. Find domain-wide delegation¶

In the Admin console: Security → Access and data control → API controls, then the Manage Domain Wide Delegation link near the bottom of that page.

It is a link, not a menu item — go straight there

This setting has moved three times, which is why it is hard to find even for a super admin. The direct URL is admin.google.com/ac/owl/domainwidedelegation.

If it will not open, you are probably in the Google Cloud console rather than the Admin console — Cloud shows you the service account but never the delegation grant.

The delegation page gives a 403, and I am a super admin

A 403 is different from a 404 or a login redirect: the page exists and Google is refusing the identity your browser is using. In order of likelihood:

You are signed into more than one Google account. admin.google.com resolves to the default account, which is often a personal Gmail — the deep link then 403s even though your admin account would be allowed. Open the link in an incognito window signed in only as the super admin, or force the account index: admin.google.com/u/1/ac/owl/domainwidedelegation (try 1, 2, …).
The role is not what it looks like. Check Account → Admin roles for the account you are actually signed in as — a delegated admin role can closely resemble Super Admin. Sign out and back in afterwards; some controls need a fresh session.
The tenant is reseller- or partner-managed. Some API controls stay with the reseller and surface as forbidden rather than hidden. Your reseller has to grant the delegation.
The edition does not have it. Workspace Individual and Essentials Starter have no domain-wide delegation. The tell: you can reach Security → Access and data control → API controls but the delegation link inside it is absent or refused.

Cases 3 and 4 cannot be worked around from Datahub. Google Chat channels still work — they need no service account at all — so an organisation in that position can use Chat for notifications and a Microsoft 365 Outlook channel, if it has one, for anything that must carry a file.

5. Delegate exactly one scope¶

Add new, then:

Field	Value
Client ID	the Unique ID from step 3
OAuth scopes	`https://www.googleapis.com/auth/gmail.send`

That single scope is everything Datahub needs. If you are offered a broader Gmail scope, do not grant it — a narrower delegation is the whole point of this model.

Delegation can take a few minutes to apply

A send attempted immediately after granting can fail with an authorisation error that looks permanent. Wait a minute or two and test again before changing anything.

6. Configure Datahub¶

In Datahub: Admin → Integrations → Google Workspace.

CredentialsGmail channelGoogle Chat channel

Client email — the service account's client_email from the JSON file (it ends in .iam.gserviceaccount.com).
Private key — the private_key value from the JSON file. Datahub writes it to the secret manager and keeps only a reference.
Enable the capabilities you want: Gmail, Google Chat, or both.

From mailbox — the address Datahub sends as. It must be a real, licensed mailbox in your domain, and the delegation from step 5 is what permits it.
Recipients — one or more addresses. Unlike the Microsoft 365 integration, a Gmail channel has no per-action recipient override, so the channel's own recipient list is the one that is used.
Pick which events the channel subscribes to.

In Google Chat, open the space → Space settings → Apps & integrations → Webhooks → Add webhook.
Copy the generated URL and paste it into Datahub.
Pick which events the channel subscribes to.

The URL is the credential — treat it like a password and regenerate it in Chat if it leaks.

The checkboxes come in two independent groups.

Tasks & workflows — task completion, task overdue, and the three workflow signals, with All task & workflow events covering the lot.

Alerts — everything that needs attention, whichever part of Datahub raises it: an alert rule matching its threshold, and a scheduled pipeline run that failed, got stuck, or never started. All alerts (any source) is the switch for "send every alert to this space" — the setup for one ops or on-call space, instead of adding an action to every alert rule you write. It keeps covering new alert sources as they are added.

The alert group sits outside "all events" deliberately: alerts are the highest-volume signal Datahub produces, so a channel set to "all events" before this option existed does not start receiving them without an admin asking. Ticking one group's "all" leaves the other group's choice alone — you can have both.

If an alert rule also names this exact channel in its own Google Workspace action, that action delivers and the subscription stays quiet: one message per fire, in the format the rule configured. Subscribed alerts use Datahub's built-in alert message (rule name, current value, threshold) — a per-rule message template or an .xlsx attachment belongs to a rule's own action.

Governance gaps — the gaps Datahub finds in how your data is governed, for example a domain with no steward: when one opens, when it is fixed or eased (still there, under the level that sends a notice), and a daily digest at 08:00 (Amsterdam time) of what is new, fixed, eased and still open, sent only while a gap is open or something changed. If none of your subscribed channels could take a digest, the next one lists its changes again; if some took it, a channel that could not does not get that day's changes again. Neither "all" option includes them; tick the ones you want. The people who can fix a gap also get it in their Datahub notifications. Datahub switches its gap checks on for channels one at a time: until a check is on, its gaps stay on the Administration page, so a new subscription can be quiet for a while.

Sending a spreadsheet¶

An alert can attach its full result set as an .xlsx, and on Google Workspace a Gmail channel is the one that can carry it.


Gmail	Carries the file as a normal mail attachment.
Google Chat	Cannot. A Chat webhook posts a card payload with no file field, so Datahub refuses the send with a message saying so rather than delivering the card with the file quietly missing.

The toggle is on the alert action, disabled with the reason on it when the chosen channel cannot carry a file. See Alerts for the row limits and the truncation behaviour, which are the same on both providers.

Where a file may go can be restricted

An administrator can limit which recipient domains may receive an attachment, under Admin → Defaults → Alert attachments. It governs the attached file only, never the result table inside a message.

Day-2: testing and audit¶

The Channels tab has a Send test message button on every channel row, dispatching through the same code path live notifications use.
The Activity tab is the audit trail — the last 100 attempts with their status, HTTP response code, any error, and the filename, row count and size of any file the dispatch carried. A file is not visible in the message the way an inline table is, so this row is the only place to see how much data left.

Limitations¶

Limitation	Why	What it means for you
Gmail needs domain-wide delegation.	`gmail.send` sends as a mailbox, and only a Workspace admin can permit that.	A Google Cloud project admin cannot complete this alone; step 5 needs the Admin console.
A Chat webhook cannot carry a file.	Its payload is a card with no file field.	Use a Gmail channel for attachments, or a Microsoft 365 Outlook channel.
A Gmail channel has no per-action recipient override.	The cross-module dispatch contract forwards overrides to Microsoft 365 only.	To send the same alert to different addresses, create one Gmail channel per destination.
The From mailbox must be real and licensed.	It is a mailbox, not a label.	A group alias or an unlicensed account will not work.
Chat webhook URLs are bearer secrets.	Anyone holding one can post to the space.	Do not paste them into tickets; regenerate in Chat on suspected leakage. Admins with Integrations: Manage can read them, by design, so they can rotate them.