Sync users from Google Workspace

Google Workspace directory sync keeps your Hook user list aligned with Google. Once it's connected, Hook pulls the Google Groups you choose straight from your Workspace, so you stop chasing CSV exports every time someone joins or leaves.

Hook connects through an account of its own, created just for your organization. Nobody at your company hands Hook a password or a token, and no person's Google account is involved. Instead, a Google Workspace super admin gives that account a read-only admin role, and Hook reads your directory as itself from then on. If the super admin who set it up later leaves, nothing changes.

It takes a few minutes in Hook plus a few minutes in the Google Admin console, and you can split the two halves between people.

Before you begin

• You need the org admin role in Hook. That is who clicks Connect and Verify on the Integrations page.
• You need a Google Workspace super admin. Creating an admin role and assigning it to an account both happen in the Google Admin console, and only a super admin can do them. It can be you or a colleague; Hook shows you everything the super admin needs to copy across.
• Hook reads users, groups, and organizational units, and nothing else. The role you create is read-only. Hook never asks for write access and never changes anything in Google.
• What Hook reads, and why. To expand a group and to notice when someone has left it, Hook reads your whole directory on every sync: the user list, the group list, and the members of the groups you selected. It keeps only the people who belong to a selected group. Users outside your selection are read to work out membership and departures, then discarded; they are never stored in Hook.
• You'll want at least one Google Group. Hook syncs Google Groups, so an organization with no groups has nothing to select yet. See If you have no groups yet below.

Connect Hook to Google Workspace

Choose groups and preview

Once Verify succeeds, Hook opens the group picker straight away. If you come back later, expand your directory row and click Manage groups in the Synced groups footer.

If you have no groups yet

Hook syncs Google Groups, so if your Workspace has none, the picker shows an empty state asking you to create one. Create a group in the Google Admin console under Directory, then Groups, or at Google Groups, add the people you want in Hook, and come back to Integrations. Expand your directory row and click Manage groups to pick it.

For a small organization that wants everyone in Hook, a single group whose membership is the whole organization works as a whole-directory scope. When a group's members include the "everyone in your organization" entry that Google offers, Hook expands it to every active user in your Workspace, across all of your domains, and the preview shows the resulting count.

After the first sync

Your row in Synced directories now shows how many groups are in scope. Expand it for three columns: the synced groups, the members of whichever group you select, and the email domains those users receive mail on. Those domains need approving before anyone on them can be sent a simulation. See Authorize recipient domains.

Google Workspace connections sync on demand today. Click Sync now in the sync block whenever you want Hook to re-read membership, and it also syncs whenever you save a group selection or change your scope. The sync block shows when the last sync ran and whether it succeeded, and the run history underneath it lists earlier runs. Scheduled refreshes for Google Workspace are on the way. To change which groups are synced, reopen Manage groups; your current selection is pre-checked.

Two things to know about who gets deactivated. People are deactivated in Hook when they drop out of every synced group, and also when their Google account is suspended or archived, because Hook reads each member's account status on every sync. Restoring the account in Google brings the person back on the next sync with their history intact. If something looks wrong after a sync, see Troubleshoot directory sync.

MSP-managed organizations

If your organization is managed by an MSP, the MSP admin usually does the Hook half and your Workspace super admin does the Google half. The MSP admin clicks Connect on your organization's Integrations page and forwards three things to your super admin: Hook's account email from the panel, the three privileges listed above, and the name of the Hook organization it belongs to, so the role is assigned from the right Workspace.

Nothing in Hook has to happen in the same sitting. Once the super admin confirms the role is assigned, any Hook admin with access to the organization, whether at the MSP or at the customer, opens the panel from the directory row and clicks Verify.

When something goes wrong

The role was removed

Hook keeps syncing for as long as the role stays assigned to its account. If a super admin removes the assignment, or deletes the role, the next sync is turned away. Hook gives Google a short grace period for a role that was only just changed, and after that the run fails and your directory row switches to Reauthorization needed. In that state the row offers only Reconnect and Disconnect, and Sync now is hidden. Your saved groups and synced users are untouched; nobody is deactivated by the status itself.

To fix it, ask your super admin to assign the role to the same account email again, then click Reconnect. That reopens the panel with the same email showing. Click Verify; nothing else is needed on the Google side. When it succeeds, Hook opens the group picker with your saved selection pre-checked and asks you to review it before syncing resumes. Re-confirming the same groups is enough.

Hook's account was deleted at Google

The account Hook created for your organization lives on Hook's side, and a super admin cannot delete it from your Admin console. If it is ever gone all the same, the panel says the account needs to be re-created. Click Reconnect: Hook creates a replacement, which has a new email address. Copy the new email, have your super admin assign the role to it exactly as on first connect, and click Verify. The old email no longer does anything, so the old assignment can be removed. If you had also set up Google Direct Send, its delegation entry has to be granted to the new account as well.

Provisioning failed

If Hook could not create the account when you clicked Connect, the panel says so and the directory row stays in its connecting state. The usual cause is that Hook has reached its Google account capacity, which Hook's team is alerted about automatically. There is nothing to change in Google. Click Reconnect on the row to try again, or Cancel connection to clear it and start over later. If it keeps failing, contact support.

A Hook-side error

Any message that says the problem is on Hook's side means exactly that: Hook's own connection to Google, not your role assignment, is at fault. Hook's team has been alerted. Nothing you assigned has been revoked, and there is nothing for your super admin to do. Try again later, or contact support if it persists.

Remove Hook's directory role

Hook cannot remove a role your super admin assigned, so switching Hook off in Google takes two steps, and the order matters.

1. In Hook, click Disconnect on your directory row and confirm. Syncing stops on Hook's side. Your saved group selection is kept, and so is Hook's account for your organization, so reconnecting later shows the same email and only needs a Verify if the role is still assigned.
2. In the Google Admin console, go to Account, then Admin roles, open the role you created for Hook, choose Assign service accounts, and remove Hook's account email from the list. If nothing else uses the role, you can delete the role itself.

Disconnecting in Hook first means the removal never lands as a failed sync or a Reauthorization needed status.

Removing a Gmail delegation entry for Google Direct Send

This section only applies if your organization also set up Google Direct Send, which places phishing simulations straight into Gmail inboxes. Direct Send uses the same Hook account as directory sync but is granted separately, through a domain-wide delegation entry that carries only Gmail permissions. Removing the directory role does not remove that entry, and removing the entry does not affect directory sync.

To remove it, in the Google Admin console go to Security, then Access and data control, then API controls, then Manage Domain Wide Delegation. Find the entry whose client ID matches Hook's account for your organization and remove it. Switch your campaign delivery method away from Google Direct Send in Hook before you do, so no campaign is left trying to deliver through an entry that is gone.

Related

For Gmail delegation setup and removal, see Set up Google Direct Send. The delegation entry lives in the Google Admin console under Security, then Access and data control, then API controls, then Manage Domain Wide Delegation. Disconnecting this directory also disconnects Direct Send; remove its delegation entry in Google Admin console to revoke mailbox access.