mirror of
https://github.com/formbricks/formbricks.git
synced 2026-02-07 03:08:43 -06:00
docs: Formbricks Hubspot integration (#7212)
This commit is contained in:
Harsh Bhat
@@ -161,6 +161,7 @@
|
||||
"xm-and-surveys/core-features/integrations/activepieces",
|
||||
"xm-and-surveys/core-features/integrations/airtable",
|
||||
"xm-and-surveys/core-features/integrations/google-sheets",
|
||||
"xm-and-surveys/core-features/integrations/hubspot",
|
||||
"xm-and-surveys/core-features/integrations/make",
|
||||
"xm-and-surveys/core-features/integrations/n8n",
|
||||
"xm-and-surveys/core-features/integrations/notion",
|
||||
|
||||
183
docs/xm-and-surveys/core-features/integrations/hubspot.mdx
Normal file
183
docs/xm-and-surveys/core-features/integrations/hubspot.mdx
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: "HubSpot"
|
||||
description: "Learn how to integrate Formbricks with HubSpot to automatically create or update contacts when survey responses are submitted."
|
||||
---
|
||||
|
||||
<Note>
|
||||
Formbricks doesn't have a native HubSpot integration yet. This guide shows you how to connect Formbricks with HubSpot using automation platforms (Make.com, n8n) or custom webhooks.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before setting up the integration, you'll need:
|
||||
|
||||
1. **A Formbricks account** with at least one survey that collects email addresses
|
||||
2. **A HubSpot account** with API access
|
||||
3. **HubSpot API credentials** (see authentication options below)
|
||||
4. **Automation service** like Make, n8n, or ActivePieces (for no-code methods)
|
||||
|
||||
### HubSpot Authentication Options
|
||||
|
||||
HubSpot offers two main ways to authenticate API requests:
|
||||
|
||||
#### Option A: OAuth 2.0 via Public App (Recommended)
|
||||
|
||||
OAuth is the recommended approach for production integrations. When using Make.com or n8n, they handle OAuth authentication for you through their built-in HubSpot connectors.
|
||||
|
||||
#### Option B: Legacy Private Apps (Simple Setup)
|
||||
|
||||
For custom webhook handlers, you can use a Legacy Private App which provides a static access token. While marked as "legacy," these apps remain fully supported by HubSpot.
|
||||
|
||||
To create a Legacy Private App:
|
||||
|
||||
<Steps>
|
||||
<Step title="Open HubSpot Settings">
|
||||
Go to your HubSpot account **Settings** and navigate to **Integrations** → **Private Apps**.
|
||||
</Step>
|
||||
<Step title="Create the App">
|
||||
Click **Create a private app** and give it a name (e.g., "Formbricks Integration").
|
||||
</Step>
|
||||
<Step title="Configure Scopes">
|
||||
Under **Scopes**, add `crm.objects.contacts.write` and `crm.objects.contacts.read`.
|
||||
</Step>
|
||||
<Step title="Get Your Access Token">
|
||||
Click **Create app** and copy the access token.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
For more information on HubSpot's authentication options, see the [HubSpot Authentication Overview](https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth).
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Method 1: Using Make.com (Recommended for No-Code)
|
||||
|
||||
<Note>
|
||||
Before starting, ensure your survey has clear `questionId` values set. You can only update these before publishing. If your survey is already published, duplicate it and update the question IDs in the copy.
|
||||
</Note>
|
||||
|
||||
<Steps>
|
||||
<Step title="Set Up Your Survey">
|
||||
Make sure your survey has meaningful `questionId` values for each question. This makes mapping responses to HubSpot fields easier.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create a New Make.com Scenario">
|
||||
Go to [Make.com](https://make.com) and create a new scenario. Search for **Formbricks** and select it as your trigger, then choose **Response Finished** as the trigger event.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Connect Formbricks to Make">
|
||||
Click **Create a webhook**, enter your Formbricks API Host (default: `https://app.formbricks.com`), add your Formbricks API Key (see [API Key Setup](/api-reference/rest-api#how-to-generate-an-api-key)), and select the survey you want to connect.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Add the HubSpot Module">
|
||||
Click the **+** button after the Formbricks trigger, search for **HubSpot**, choose **Create or Update a Contact** as the action, and connect your HubSpot account.
|
||||
</Step>
|
||||
<Step title="Map Formbricks Fields to HubSpot">
|
||||
Map the Formbricks response fields to HubSpot contact properties:
|
||||
|
||||
| HubSpot Field | Formbricks Field |
|
||||
| ------------- | ---------------- |
|
||||
| Email | `data.email` (your email question ID) |
|
||||
| First Name | `data.firstName` (if collected) |
|
||||
| Last Name | `data.lastName` (if collected) |
|
||||
| Custom Property | Any other `data.*` field |
|
||||
|
||||
You can also map metadata: `meta.country`, `meta.userAgent.browser`, `survey.title`.
|
||||
</Step>
|
||||
<Step title="Test and Activate">
|
||||
Submit a test response to your Formbricks survey, verify the contact appears in HubSpot, and turn on your Make scenario.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Method 2: Using n8n (Self-Hosted Option)
|
||||
|
||||
<Note>
|
||||
The Formbricks n8n node is available as a community node. Install it via **Settings** → **Community Nodes** → install `@formbricks/n8n-nodes-formbricks`.
|
||||
</Note>
|
||||
|
||||
<Steps>
|
||||
<Step title="Set Up the Formbricks Trigger">
|
||||
Create a new workflow in n8n, add the **Formbricks** trigger node, connect it with your Formbricks API Key and host, select **Response Finished** as the event, and choose your survey.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Add the HubSpot Node">
|
||||
Add a new node and search for **HubSpot**, select **Create/Update Contact** as the operation, and connect your HubSpot account (n8n supports both OAuth and access token authentication).
|
||||
</Step>
|
||||
<Step title="Configure Field Mapping">
|
||||
In the HubSpot node, map the fields:
|
||||
|
||||
```
|
||||
Email: {{ $json.data.email }}
|
||||
First Name: {{ $json.data.firstName }}
|
||||
Last Name: {{ $json.data.lastName }}
|
||||
```
|
||||
|
||||
For custom HubSpot properties, use the **Additional Fields** section to add mappings like `survey_source`, `response_id`, and `submission_date`.
|
||||
</Step>
|
||||
<Step title="Test Your Workflow">
|
||||
Click **Listen for event** in the Formbricks trigger, submit a test survey response, verify the data flows through to HubSpot, and activate your workflow.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Method 3: Using Webhooks (Custom Integration)
|
||||
|
||||
For maximum flexibility, you can use Formbricks webhooks with a custom endpoint that calls the HubSpot API directly. This approach is ideal for developers who want full control.
|
||||
|
||||
<Note>
|
||||
This method requires a HubSpot access token. You can use a Legacy Private App token (simplest) or implement OAuth 2.0 for production applications.
|
||||
</Note>
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Formbricks Webhook">
|
||||
Go to **Configuration** → **Integrations** in Formbricks, click **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished** as the trigger, and choose the surveys to monitor.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Build Your Webhook Handler">
|
||||
Your webhook handler needs to:
|
||||
- **Receive the Formbricks webhook** - Accept POST requests with the survey response payload
|
||||
- **Extract contact data** - Parse the email and other fields from `data.data` (keyed by your `questionId` values)
|
||||
- **Call the HubSpot API** - Use the [HubSpot Contacts API](https://developers.hubspot.com/docs/api/crm/contacts) to create or update contacts
|
||||
- **Handle duplicates** - HubSpot returns a 409 error if a contact with that email exists; search and update instead
|
||||
|
||||
You can deploy using serverless functions (Vercel, AWS Lambda, Cloudflare Workers), traditional servers, or low-code platforms. For webhook signature verification, see the [Webhooks documentation](/xm-and-surveys/core-features/integrations/webhooks).
|
||||
</Step>
|
||||
<Step title="Deploy and Test">
|
||||
Deploy your webhook handler to a publicly accessible URL, add the URL to your Formbricks webhook configuration, submit a test survey response, and verify the contact appears in HubSpot.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Contact Not Created in HubSpot
|
||||
|
||||
1. **Check the email field**: Ensure your survey has an email question and you're mapping the correct `questionId`
|
||||
2. **Verify API token**: Make sure your HubSpot access token has the required scopes (`crm.objects.contacts.write` and `crm.objects.contacts.read`)
|
||||
3. **Check for duplicates**: HubSpot returns a 409 error if a contact with that email already exists
|
||||
|
||||
### Webhook Not Triggering
|
||||
|
||||
1. Verify the webhook URL is publicly accessible
|
||||
2. Check that **Response Finished** trigger is selected
|
||||
3. Ensure the survey is linked to the webhook
|
||||
|
||||
### Testing Your Integration
|
||||
|
||||
1. Use a unique test email for each test
|
||||
2. Check HubSpot's **Contacts** page after submitting a response
|
||||
3. Review your webhook handler logs for errors
|
||||
|
||||
---
|
||||
|
||||
Still struggling or something not working as expected? [Join our GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we're happy to help!
|
||||
@@ -15,6 +15,8 @@ At Formbricks, we understand the importance of integrating with third-party appl
|
||||
|
||||
* [Google Sheets](/xm-and-surveys/core-features/integrations/google-sheets): Automatically send responses to a Google Sheet of your choice.
|
||||
|
||||
* [HubSpot](/xm-and-surveys/core-features/integrations/hubspot): Create or update HubSpot contacts automatically when survey responses are submitted.
|
||||
|
||||
* [Make](/xm-and-surveys/core-features/integrations/make): Leverage Make's powerful automation capabilities to automate your workflows.
|
||||
|
||||
* [n8n](/xm-and-surveys/core-features/integrations/n8n)(Open Source): Automate workflows with n8n's no-code automation tool
|
||||
|
||||
Reference in New Issue
Block a user