Drupal HubSpot integration: sending Webform leads to HubSpot
Marketing and web teams usually need every form on the Drupal site to create or update a lead in HubSpot, without someone copying submissions by hand. The supported method is the contributed HubSpot module, which integrates Webform with the HubSpot API so that submissions go directly into HubSpot's lead management system. Drupal core and contributed projects on Drupal.org are licensed under GPL-2.0-or-later and there is no paid edition of Drupal, so the license cost is zero. The money goes into build, configuration, testing and ongoing support, and into any HubSpot subscription you already pay for. The Drupal.org project page for the HubSpot module is the next read: HubSpot module on Drupal.org.
The work starts with decisions, not configuration. Confirm which Webform forms should create leads, which HubSpot object each one writes to, and which Drupal fields map to HubSpot contact properties. Check the module's supported Drupal core version against your site's current branch before you commit, because the module is a contributed project with its own release cycle. Then decide who owns the HubSpot API credentials and how they are stored, since a leaked token lets anyone write to your CRM. Plan a test form and a staging HubSpot portal or sandbox so that mapping errors do not reach live contact records.
Consent capture is the decision most often left too late. Record the consent wording shown on each form, the timestamp and the form version alongside the submission, and map those values to the HubSpot properties your legal and marketing teams have agreed. Confirm with your privacy lead which lawful basis applies in each region you market to, because the module moves data but does not decide what consent is valid. Also plan for failures: an API timeout or a rejected field should be logged and visible to someone who can retry it, or leads will disappear silently. If the team wants less custom behavior, HubSpot's embedded forms are an alternative, but they move form hosting and data capture outside your Webform setup, so compare them against your consent and field-mapping requirements first.
What a Drupal HubSpot integration needs before the build
A HubSpot lead capture integration depends on four things being settled before any code is written: the Drupal and PHP versions, the contributed modules, the HubSpot account and its access model, and the network path from the web tier. Each card below is a decision or check that is cheapest to resolve at the start and expensive to discover during the build.
Drupal and PHP version target
Choose the Drupal release first, because it sets the PHP runtime your hosts must provide. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, and no supported Drupal version runs on PHP 7. Drupal 10 reaches end of life on December 9, 2026, so a new build on Drupal 10 starts with a planned upgrade. Confirm that the Webform and HubSpot module releases you plan to use support the chosen core version before you lock the version.
Webform and HubSpot module dependencies
The HubSpot module connects Webform to the HubSpot API, so Webform is a hard dependency and the forms you want to send must be built as Webform forms. Check the HubSpot module's project page for the release line that matches your core version, and review its open issues before committing. Pin contributed module versions in Composer so that an update to Webform or HubSpot does not change form behavior during a release.
HubSpot account and API access
Confirm that the client's HubSpot subscription and user permissions allow API access for the integration, and decide who owns the credential. The client, not DeployOpen, sets the scopes of the private app or token, and the scopes should cover only the contact and form reads and writes the mapping needs. Ask HubSpot to confirm the current authentication method and any plan-level limits before the build, because these change over time and this page does not state them.
Token storage and rotation
Store the HubSpot credential outside the site database and the exported configuration, typically in environment variables or a secrets manager that the hosting platform controls. Define who can rotate the token, how a rotation is rolled out across web nodes, and how a revoked token is detected. A credential that lives in a configuration export can end up in a repository, so treat the export as sensitive until it is checked.
Outbound HTTPS from the web tier
Submissions are sent from the Drupal web servers to the HubSpot API over outbound HTTPS, so the firewall, proxy and egress rules must allow that path from every node that handles form posts. In containerized or air-gapped environments, confirm that DNS resolution, TLS trust and any corporate proxy settings work inside the container, not only on a workstation. Test with a real submission from a production-like host before the build is marked complete.
Consent and data handling decisions
Decide before the build which consent wording the form shows, where that consent is stored in Drupal and whether HubSpot receives the consent value as a contact property. Confirm with the client's legal or privacy team which lawful basis and retention rules apply to lead data in each market. DeployOpen can build the capture and record, but the wording and the legal basis are the client's decisions and should be documented before testing starts.
How to configure the HubSpot module with Webform, step by step
This sequence takes a Drupal site from a clean install to tested lead capture, with each Webform submission arriving in HubSpot as a contact that carries the consent record your team agreed to. Each step ends with a check so that problems surface before the form goes live.
Install and enable the required modules
A Drupal developer adds the HubSpot module and its Webform dependency to the site's Composer project, then enables both with Drush or the Extend screen in a development environment. Confirm the exact module versions against your Drupal core version on the project page on Drupal.org before you run the install, because the module's compatibility range determines which branch you use. Done means the HubSpot integration appears as enabled in the module list and the site's status report shows no missing requirements.
Create HubSpot credentials for the integration
An administrator in the HubSpot account creates the authentication credentials the module needs, either a private app access token or the authentication method the module documentation currently recommends. Grant only the scopes for contacts and forms that the lead capture flow requires, and record which HubSpot account and portal the credentials belong to. Done means you have a credential stored in your secrets manager, not in the codebase, and you can name the HubSpot portal it targets.
Connect the Drupal site to the HubSpot account
A Drupal administrator enters the credentials on the HubSpot module configuration page, or supplies them through environment configuration if your deployment keeps secrets out of the database. Save the settings and run the module's connection test or an equivalent API call from the admin interface. Done means the connection test reports success and the site log shows no authentication errors for the HubSpot API.
Map Webform fields to HubSpot properties
A site builder opens the Webform that will capture leads and maps each form element to a HubSpot contact property, such as email, first name, company and the properties your sales team uses for lead routing. Check the property internal names in HubSpot, because the mapping must match them exactly, and agree with sales which fields are required. Done means every required HubSpot property has a mapped Webform element, and the mapping is documented in the project's configuration export.
Add consent fields to the form and map them
A site builder adds explicit consent checkboxes or equivalent elements to the Webform, worded with your legal or privacy team, and maps them to the HubSpot properties your marketing team uses to record marketing consent. Confirm with counsel whether the wording, default state and timestamp requirements meet the rules that apply to your audience and region. Done means a submission with consent unchecked does not set the marketing-consent property in HubSpot, and the mapped consent values are visible on the test contact record.
Test with a sandbox or test portal
A tester submits the form several times in a HubSpot sandbox or test portal, using valid, incomplete and consent-declined entries, and confirms each result in HubSpot. Include a submission with a value that already exists as a contact to see how the module handles duplicates under your settings. Done means each test submission appears as the expected contact with the mapped fields and consent values, and failed submissions are logged with a readable error.
Promote the configuration to production
The team moves the configuration export and the Composer changes through its normal release path, then repeats one controlled test submission against the production portal using a test record that sales agrees to delete. Store the production credential in your secrets manager and confirm that the production HubSpot account receives the contact. Done means a production test contact appears in HubSpot with correct fields and consent, and the team has a written record of who approved the go-live.
Mapping Webform fields to HubSpot contact properties
This table compares each Webform element on a lead capture form with the HubSpot contact property it should populate, the data type HubSpot expects and whether the property is typically required. Use it as a starting worksheet, then confirm every internal property name and option list against your own HubSpot property definitions during scoping, because portals differ in custom properties and validation rules.
| Webform element | HubSpot contact property | Expected type and format | Required in your portal? |
|---|---|---|---|
| Name (first and last) | firstname, lastname | Single-line text; split first and last name in the form if HubSpot expects separate values | Confirm; often optional unless your workflows depend on it |
| Email address | Valid email address; HubSpot uses it as the contact identity, so normalize case and trim spaces | Usually required; confirm with your HubSpot team | |
| Company | company | Single-line text; match your account naming rules to avoid duplicate companies | Confirm; required only if your lead routing depends on it |
| Country | country | Dropdown or text; align option values with HubSpot's country list or a custom property | Confirm; check whether the property is standard or custom in your portal |
| Consent checkbox | Your legal basis or subscription property (for example, a marketing consent field) | Boolean or subscription status; record the wording shown and the timestamp, not just a true value | Required when marketing email is sent; agree the exact property with your compliance lead |
| Source page or form name | A custom property such as lead source detail or hs_analytics_source_data fields where applicable | Single-line text; capture the page path or Webform ID, not free-text guesses | Optional; create the custom property before the build if reporting depends on it |
When the HubSpot module fits and when HubSpot embedded forms fit
The HubSpot module connects Webform to the HubSpot API so that a Webform submission on your Drupal site is sent directly into HubSpot's lead management system. Your site keeps the form itself, its validation rules, its field structure and the decision about what leaves Drupal. This suits organizations that want Drupal to remain the system that accepts and checks input, and that need to keep personal data handling inside rules they write and test.
- Validation stays in Drupal: Webform rules, required fields, spam defenses and conditional logic run before any data is sent, so invalid or unwanted submissions never reach HubSpot.
- Consent is captured on your pages: The consent checkbox and its wording are part of your Webform, and you decide what is stored and when the submission is sent.
- Data path is visible: Your team can see which fields are mapped, where errors are logged and what happens when the HubSpot API returns an error.
- Editorial effort is developer-led: Changing a field or adding a form usually means a configuration change and mapping review, which a Drupal developer or site builder performs.
- Maintenance is shared: Your team maintains the Drupal and module upgrades, while HubSpot changes to its API need monitoring.
Before choosing this path, confirm with your Drupal team which module version supports your Drupal version and which HubSpot account permissions the integration will use.
With HubSpot embedded forms, the form is built and hosted in HubSpot, and your Drupal page includes the form through HubSpot's embed code. HubSpot then receives and stores the submission from its own hosted form. This moves form logic, field definitions and much of the editing work into HubSpot's tools, which marketing teams often already use daily.
- Validation follows HubSpot's form rules: Field types, required fields and any progressive profiling are configured in HubSpot, so checks happen on HubSpot's side rather than in your Webform.
- Consent is configured in HubSpot: Consent options belong to the HubSpot form and its contact settings, so the wording and records must be checked against your legal basis.
- Data residency follows HubSpot: Submissions are collected on HubSpot-hosted infrastructure, so your residency review must cover HubSpot's data handling for that form, not only your own servers.
- Editorial effort is marketing-led: Marketing teams can change fields and forms in HubSpot without a Drupal release, which reduces developer involvement for routine changes.
- Maintenance is split: HubSpot maintains the form platform, while your team maintains the embed placement, page templates and any Drupal-side styling.
Ask your privacy and marketing leads to confirm which submission data HubSpot stores and where, before the embed goes live on regulated pages.
The choice depends less on feature lists than on who must answer for each part of the submission. If your compliance team needs to inspect and test validation and consent logic inside your own codebase, the module keeps that evidence in your hands. If your marketing team needs to publish and change forms quickly with little developer time, embedded forms reduce that load. Many organizations first decide which system must own the record of consent, then select the option that keeps that record accurate.
- Control over validation: The module gives you full control in Drupal, while embedded forms rely on HubSpot's configuration.
- Consent records: Decide which system stores consent evidence and whether the two systems must agree.
- Editorial speed: Embedded forms usually allow faster changes by non-developers, while module changes need a release.
- Maintenance ownership: The module adds Drupal and API upkeep to your team; embedded forms shift form upkeep to HubSpot but keep page integration with you.
- Testing scope: The module needs end-to-end tests from Webform to HubSpot, while embedded forms need checks of the page embed and HubSpot settings.
Whatever you choose, check the current module documentation on Drupal.org and document who owns each part before launch.
Securing the HubSpot credential, consent and personal data
Lead capture moves personal data from a Drupal form into a HubSpot contact record, so the credential, the retained submissions and the consent evidence all need controls. The cards below cover each control and the ongoing checks that keep them working after launch.
Keep the HubSpot token out of code
The HubSpot module authenticates to the HubSpot API with a private app access token, and that token can create and update contacts in your portal. Store it in environment variables or a secrets manager that your hosting platform controls, and reference it from configuration rather than committing it to the Drupal codebase or exporting it with configuration. Confirm with your team who can read the secret, how it is rotated, and what happens to the token when an engineer leaves.
Grant the narrowest HubSpot scopes
A private app asks for specific scopes in HubSpot, and each scope widens what a leaked token can do. Limit the app to the contact and form-submission permissions that the lead flow needs, and avoid broad account administration or deal scopes unless a later requirement calls for them. Review the granted scopes after every change to the mapping, since a new field or object often prompts a request for extra permissions.
Limit submission data kept in Drupal
Webform stores every submission in the Drupal database by default, so a form that sends data to HubSpot also keeps a second copy on your server. Decide how long submissions should remain in Drupal, configure the Webform retention settings and purge job, and exclude fields that HubSpot does not need. Ask your data protection lead whether a copy in Drupal is needed at all once the lead exists in HubSpot.
Record consent as a stored decision
Use an unticked checkbox that the visitor must actively select, and keep its wording separate from the privacy notice link. Store the consent decision, the text shown, the timestamp and the form version with the submission so you can show what the person agreed to. Map the consent value into the HubSpot contact property that your marketing team uses for opt-in, and check that both systems agree before any campaign sends email.
Review privacy notice wording with legal
The text next to the consent checkbox and the privacy notice it links to describe what happens to a person's data, including the HubSpot transfer. Have your legal or privacy team approve that wording for each form and each country you market to, and keep the approved version under change control. Engineers should not write this text themselves, and the team should re-review it when the form fields or the HubSpot use changes.
Track advisories and module updates
The Drupal Security Team publishes advisories for Drupal core and contributed projects, including the HubSpot module, with CVE identifiers and risk scores. Subscribe your team to those advisories, and schedule updates to the HubSpot module and Webform alongside core security releases. Confirm who applies a patch, who tests the lead flow afterward, and how a HubSpot API change would be detected before leads start failing silently.
Common HubSpot lead capture failures and how to fix them
This table pairs each common failure in a Webform to HubSpot setup with its likely cause and the check or fix that resolves it. Read it while testing a build or triaging a live problem, starting from the symptom your team sees. The main takeaway is that most lost leads come from credentials, property definitions or consent fields, and each is checkable in Drupal and HubSpot before launch. Confirm HubSpot-side limits and API behavior with HubSpot.
| Failure | Likely cause | Check or fix |
|---|---|---|
| API calls rejected with authorization errors | Access token expired, revoked or created with scopes that do not include contact write access | Confirm the HubSpot credential in the module settings, verify its scopes in HubSpot, and rotate it through your secrets process rather than editing it in the database |
| Field values rejected by HubSpot | Webform element type does not match the HubSpot property type, such as free text sent to a dropdown or number property | Compare each mapped Webform element with the HubSpot property type and option list, then align the option values exactly before retesting |
| Duplicate contacts appear in HubSpot | Submissions matched on email with inconsistent casing or whitespace, or a second form or import created a parallel record | Normalize email before submission, confirm the identifier HubSpot uses to match contacts, and review existing records for merge candidates |
| Consent value missing or blank | No consent checkbox mapped to a HubSpot property, or the checkbox left unchecked and the field still sent | Map an explicit consent property, send only the value the visitor chose, and test both the checked and unchecked paths |
| Submission succeeds in Drupal but never reaches HubSpot | Module set to send only on certain conditions, handler disabled on the webform, or the request failed after Drupal showed success | Review the webform handler configuration, check the Drupal logs for the failed request, and resubmit a test entry to confirm delivery |
| Intermittent errors under traffic | Concurrent submissions hit HubSpot API request limits, or slow responses exceed the timeout | Confirm current HubSpot rate limits with HubSpot, queue submissions where possible, and retry with backoff instead of failing the visitor's form |
| Leads arrive with wrong source or page data | Hidden fields not populated, or source values inherited from a cached page | Check that hidden fields are set at render time, exclude form pages from aggressive caching, and verify values in a test record |
| Errors surface only after launch | No monitoring on failed API calls and no test plan covering the live integration | Set up error logging alerts, keep a scripted test submission in the release checklist, and review failures after each Drupal or module update |
How to test lead capture before go-live and keep it working
Test every lead path in a non-production HubSpot portal before go-live. Point a staging Drupal site at a sandbox or test portal, so test submissions create contacts there and never touch live lead data, sequences or routing rules. Confirm that the HubSpot module sends each Webform submission to the right place and that a test contact shows the mapped values in the expected properties. Ask your implementation partner to document which portal, API credentials and form IDs were used for each environment, so the configuration cannot be copied to production by accident.
Build a test matrix that covers each mapped field and each consent state, not just one happy-path submission. For example, a submission with every field filled, one with only required fields, one with a blank optional field, one with a value that fails the HubSpot property type, and one for each consent option the form offers (opted in, opted out, and left unanswered where the form allows it). Record the expected result for each row, then confirm the contact record, the consent property and any list membership. Repeat the matrix whenever a field, form or mapping changes.
Monitor failed submissions in Drupal logs after launch and schedule a regression run after updates. Confirm with your developers which Drupal log channel and severity the integration writes to, and set an alert on repeated errors, since a rejected API call can fail silently from the visitor's point of view. After each bugfix release (first Wednesday of the month) and each security release (third Wednesday), as described in the Drupal core release schedule, rerun the test matrix on staging, and do the same after any update to the HubSpot module or Webform. Treat a failed test as a release blocker, not a known issue.
Questions buyers ask about the Drupal HubSpot integration
What drives the cost of a Drupal and HubSpot lead capture integration?
The cost follows the number of forms, the depth of the field mapping and the number of HubSpot objects and properties involved. A basic Webform to HubSpot contact flow is much smaller than a build that maps several forms to contacts, companies and deals, handles progressive profiling and writes consent records. The contributed HubSpot module, which integrates Webform with the HubSpot API, is GPL-2.0-or-later licensed, so there is no license fee for the Drupal side, but there may be HubSpot subscription costs that are set by HubSpot, not by the project. Ask any partner for a quote that separates one-time build work (scoping, configuration, mapping, testing, documentation) from recurring work (maintenance, upgrades, monitoring) and states what is excluded.
How long does a Drupal to HubSpot lead capture build take?
Duration depends on how many forms need to reach HubSpot, how much existing Webform and HubSpot configuration already exists, and how many people must approve the field mapping and consent wording before the build starts. Testing against a HubSpot sandbox or a non-production portal, and reviewing the results with marketing and legal, often takes as long as the configuration itself. A fixed-scope engagement sets out the deliverables and timeline in writing before work begins, so ask for the schedule and the dependencies it assumes, including who signs off each stage.
What must our team provide before the integration work starts?
Your team needs to supply four things: a HubSpot account with an API integration that the Drupal site can use, access to the portal settings needed to create or confirm contact properties, written property definitions that state what each Webform field means, and approved consent wording with a clear record of what the visitor agreed to. Your marketing and legal owners should also confirm which HubSpot object each form should write to. Missing consent wording is the most common cause of delay, because the field mapping cannot be finished until the consent text and its storage are agreed.
Can an internal team build the HubSpot integration without a partner?
Yes, an internal team with Drupal and Webform experience can build a basic integration using the HubSpot module and its documentation on Drupal.org. The skills that are harder to staff internally are the field mapping design, handling duplicate contacts, testing failure paths such as API errors or rate limits, and documenting consent capture so that it can be explained to an auditor or privacy officer. Decide whether those skills exist in-house before committing, and confirm that whoever maintains the module will also track Drupal core and module releases.
Are HubSpot embedded forms cheaper than the Drupal module approach?
HubSpot embedded forms usually need less Drupal configuration, because the form is hosted and submitted by HubSpot through a script or iframe. The trade-off is control: the Drupal module keeps submissions inside Webform, lets you add validation, conditional logic and server-side handling, and lets you tie the lead to other Drupal data. Embedded forms also raise questions about cookie consent, styling and accessibility that your team must still test. Compare the total effort for both options, including the consent and accessibility work, rather than only the Drupal configuration effort.
What does ongoing support for the HubSpot integration involve?
Ongoing work covers keeping the Drupal core, Webform and HubSpot module on supported versions, checking that HubSpot API changes do not break submissions, reviewing failed submissions, and updating field mappings when marketing changes its properties. Drupal core has a predictable schedule: bugfix releases come out on the first Wednesday of each month and security releases on the third Wednesday, so plan a regular update window. Support can be handled by an internal team or under a retainer, and the agreed scope should state response expectations and who monitors the integration.
Does the HubSpot module handle consent records on its own?
The HubSpot module sends submitted data to HubSpot, but consent capture is a design decision that your team must define. Store the consent choice with the submission, record the wording and version shown to the visitor, and map the consent field to the HubSpot property your marketing team uses for communication permissions. Confirm with your privacy or legal team which regimes apply to your audience before go-live, because DeployOpen prepares controls and evidence for assessments but does not issue audit reports or certifications.
How DeployOpen scopes and delivers Drupal HubSpot integrations
DeployOpen is a Chainscore Labs company that plans, implements, customizes, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure. For Drupal and HubSpot lead capture, we start from a written scope covering the Webform fields, the HubSpot properties they map to, and the consent wording, then build and hand over the working integration in your environment.
How we scope
- Inventory every Webform that should create HubSpot leads, along with the fields each one collects and the HubSpot properties they should populate.
- Agree the consent model in writing, including which checkbox wording is stored and how opt-in status is recorded against each submission.
- Confirm the HubSpot account details, API access method and Drupal environments that will be connected, then fix scope and deliverables before work starts.
How we build
- Configure the contributed HubSpot module with Webform on a non-production Drupal site, mapping each field to its agreed HubSpot property.
- Test submissions with valid, empty and malformed values, and check that duplicate contacts and failed API calls are handled as the scope defines.
- Compare the module-based approach with HubSpot embedded forms against your consent and data handling requirements, and record the decision.
How we hand over
- Deliver field mapping tables, consent configuration notes and the test cases used, so your team can see exactly what each submission sends.
- Document the Drupal, module and HubSpot settings in a runbook that names the owner of each credential and where it is stored.
- Walk your developers and marketing operations staff through the configuration and the checks to run after each Drupal or module update.
How we support
- Ongoing support, module updates and continuous testing are available as a retainer, scoped in writing alongside the initial work.
- Retainers can cover reviewing module release notes and Drupal core updates that could affect the Webform and HubSpot connection.
- Ask any provider to confirm which Drupal and module versions their scope targets, and whether a retainer covers changes to HubSpot's API.
