Webform HubSpot Sync

Introduction

Webform HubSpot Sync connects Webform to
HubSpot CRM, so form submissions on your Drupal site show up as leads in
HubSpot without a middleman integration platform. It talks to HubSpot's Forms API directly — no HubSpot API
key, only a portal ID and a per-form HubSpot form ID, both set from one settings screen.

Two ways to get submissions into HubSpot are provided, and both feed the same audit trail: push each submission
the moment it's saved, or run an on-demand batch migration over existing submissions.

Project Summary

Get Webform submissions into HubSpot reliably — in real time by default, with automatic retry on failure and
a full record of every attempt, success or not.

Features

• One settings screen (Configuration → Web services → Webform HubSpot Sync) maps each webform to a HubSpot form ID against a single HubSpot portal ID — no per-webform configuration duplication.
• Real-time push: mapping a webform on the Settings screen automatically attaches a HubSpot sync handler to it, so submissions are sent to HubSpot as soon as they're saved — no separate per-webform setup step, and removing the mapping removes the handler again.
• Automatic retry: a failed first attempt is hooked into Drupal's Queue API and retried with exponential backoff (up to 5 attempts) via cron, instead of being silently dropped.
• Persistent audit log (Sync log tab) records the outcome — success, failed, or skipped — of every sync attempt from both paths (real-time, migrate), with a one-click Retry on any failed row.
• On-demand Migrate form for batch-syncing a webform's existing submissions, optionally scoped to a date range, with a dry-run preview before anything is actually sent.
• Per-webform field-name mapping and required-field fallback defaults, so Drupal field machine names don't have to match HubSpot property names exactly.

Post-Installation

After installing the module:

1. Go to Configuration → Web services → Webform HubSpot Sync (/admin/config/services/webform-hubspot-sync) and enter your HubSpot Portal ID, then add a mapping row for each webform you want to sync (webform → HubSpot form ID). Saving turns on real-time push for that webform immediately.
2. Go to Sync log any time to review attempts and retry failures.
3. To backfill submissions that existed before the mapping was configured, use the Migrate tab.

Additional Requirements

• Drupal 10.3+ or 11
• Webform

No HubSpot API key or private app token is required — the module uses HubSpot's public Forms API, identified
only by portal ID and form ID.

Similar projects

Marketing automation platforms like HubSpot are more commonly integrated via general-purpose connector tools
(Zapier, Make, native embed forms) or full CRM modules that sync many entity types bidirectionally. This module
takes a narrower, Webform-specific approach on purpose: one direction (Drupal → HubSpot), one entity type
(webform submissions), with real-time push, retry, and an audit trail built in rather than left to an external
integration platform.

Supporting this Module

Bug reports, feature requests, patches, and documentation improvements are welcome through the Drupal.org issue
queue.

Community Documentation

Documentation is available in the project repository's README, including configuration steps and troubleshooting
for submissions that don't reach HubSpot.

Permissions

• Administer HubSpot sync settings (restricted) – manage the portal ID and webform mappings, run migrations, and view/retry the sync log.

Architecture

• HubSpotClient – talks to HubSpot's Forms API and holds the field-name mapping logic (Drupal field name → HubSpot property name), with a generic fallback map for common field name variants.
• WebformSyncManager – the shared orchestration point: resolves a webform's mapped submissions, applies field maps and required defaults, calls HubSpotClient, and records the outcome. Used by both the real-time handler and the Migrate batch, so both log to the same place.
• HubspotSyncWebformHandler – a Plugin/WebformHandler plugin admins attach per webform; pushes on postSave() and queues a retry on failure.
• RetrySyncQueueWorker – a Queue API worker that retries a failed submission with exponential backoff, re-queueing itself with an incremented attempt count until it succeeds or hits the attempt limit.
• SyncLogStorage – records and paginates the audit trail (webform_hubspot_sync_log table).
• SyncLogController / SettingsForm / MigrateForm – the three admin screens (Sync log, Settings, Migrate) under one tabbed settings page.

The module is fully compatible with Drupal 11.