HubSpot + Drupal integration

A membership organization’s Drupal site carries more than pages. It holds the member’s login, the profile behind the member directory, the pages only members can open, and the forms for joining, renewing and registering for events. HubSpot holds the other half: the marketing record, the email subscriptions and the workflows that chase a renewal. Left unconnected, a member who lapses in HubSpot keeps their access on the site. A newsletter preference changed on the site never reaches the system that sends the email.

Not every Drupal site has members, and a site that only needs its forms and page views in HubSpot has a smaller job. HubSpot’s help centre has a Drupal site paste the tracking code into a block. A form either embeds HubSpot’s own form or sends a Webform submission to HubSpot’s form endpoint. The decisions there are which of the two the site uses, and whether its domain sits in HubSpot’s tracking settings. HubSpot marks embedded submissions from a domain missing there as spam.

The membership case turns on ownership. Sign-in stays in Drupal’s user accounts: HubSpot’s memberships gate content HubSpot hosts on its own connected domains, so they cannot stand in for a Drupal login. Email consent belongs to HubSpot, which keeps subscription status per email address. The membership record belongs wherever renewals are managed, and when that is HubSpot, the site’s roles have to follow it.

Five records carry a membership site. The member’s account becomes a HubSpot contact, keyed on the account’s UUID in a unique HubSpot property rather than on the email address. Members change their address. The UUID is the identifier JSON:API itself uses for the account, and HubSpot allows partial upserts only on a custom unique property, never on email. Email still makes the first match, for people who were contacts before they had an account.

Webform submissions arrive as HubSpot form submissions, sent with the visitor’s hutk tracking cookie, so the form’s workflows fire and the page history joins the right contact. Member organizations, where the site keeps them as content, become companies keyed on the node’s UUID.

Two records follow HubSpot. The membership state lives there, and a change sets the member’s role in Drupal, which is what the directory view and the gated pages read. Email preferences are the one place email is the key, because HubSpot keeps subscription status against the address. The site’s preferences form reads the current status from HubSpot and writes each change back to it.

The shape is a webhook queue running both ways, with a reconciliation sweep behind it. Drupal core sends no webhooks, and the contributed Webhooks module offers only a release candidate. So a small custom module hooks the account save and the Webform submission, and posts a signed event to our service. The service queues each event and writes HubSpot. Accounts become a batch upsert on the UUID property, each Webform entry a form submission, and each preference change a subscription update by email address.

HubSpot’s changes come back through a webhook subscription on the app that holds the integration’s token. A workflow’s Send a webhook action also works, and needs Data Hub Professional or Enterprise. The service checks HubSpot’s signature, queues the event and passes the membership state to a narrow route in the module, which sets the role.

The sweep reads the JSON:API user collection filtered on the changed timestamp past a stored watermark, and replays whatever the events missed. Drupal documents no API rate limit, so the sweep paces itself for the host. The watermark, the UUID to contact links and a replay endpoint live in the service.

What decides the route on a Drupal site is direction. If records only travel into HubSpot, contributed modules can do it. Hubspot Forms embeds HubSpot’s own forms and has a stable release covered by drupal.org’s security advisory policy. The HubSpot module sends Webform submissions instead, but it offers only release candidates, which the policy does not cover.

Drupal Bridge, the app in the HubSpot App Marketplace, sends Webform entries to HubSpot and lists Drupal users, Commerce orders and companies as two-way sync. Its published code takes one HubSpot webhook, for contact deletions, and marks the linked Drupal user’s sync status as deleted. Neither the listing nor the code claims role or member directory sync, and the module has no drupal.org release or advisory coverage, which matters on a site with member logins.

Once roles, the directory and email preferences have to follow HubSpot back into Drupal, the job needs a custom API integration. Zapier and Make both document Drupal connectors, but each triggers on new content only, which leaves accounts and roles to raw API calls.

1. Scope. We settle who owns each record: the login in Drupal, consent in HubSpot, the membership wherever renewals run. Then we list the forms, roles and directory fields in scope.
2. Architect. We fix the UUID key and its HubSpot property, the role mapping, the webhook route, the sweep cadence and the permissions the API account holds.
3. Build. Drupal has no vendor sandbox and needs none, because the software carries no licence fee. We build against a copy of your site on a staging host and a HubSpot sandbox, with a portal allowlist that fails closed.
4. Validate. We load every existing account, compare counts by role, and submit each form once to confirm HubSpot accepts it.
5. Operate. Cutover is a token swap. We watch the queue and the sweep, and retest the module on each Drupal minor release and on Drupal 12.