> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect HubSpot

> Sync contacts, deals, and activities between Hiveku and HubSpot

If HubSpot is your source of truth for customer data, this guide gets forms, emails, and site events from Hiveku flowing in — and HubSpot updates flowing back out.

<CardGroup cols={2}>
  <Card title="Via Zapier" icon="plug">
    Easiest. No code. Uses the built-in HubSpot + webhook connectors.
  </Card>

  <Card title="Via HubSpot API" icon="code">
    More control. Requires a HubSpot Private App token.
  </Card>
</CardGroup>

<Tabs>
  <Tab title="Via Zapier">
    See [Connect Zapier](/how-tos/connect-zapier) for the full setup. HubSpot is one of Zapier's best-supported integrations — you can create contacts, update deals, log calls, and trigger HubSpot workflows in minutes.

    Use this path when:

    * You don't want to manage API tokens
    * Volume is under a few thousand events per month
    * You need simple field mapping, not complex transforms
  </Tab>

  <Tab title="Via HubSpot API">
    Gives you direct access to the HubSpot API for any object or workflow. Pick this if you need custom objects, high volume, or complex transforms.

    ## Step 1: Create a HubSpot Private App

    <Steps>
      <Step title="Log in to HubSpot">
        Go to [app.hubspot.com](https://app.hubspot.com).
      </Step>

      <Step title="Open Private Apps">
        Navigate to **Settings > Integrations > Private Apps**. Click **Create private app**.
      </Step>

      <Step title="Name and describe it">
        Name: `Hiveku Integration`. Description: whatever helps your future self remember.
      </Step>

      <Step title="Grant scopes">
        On the **Scopes** tab, enable:

        * `crm.objects.contacts.write`
        * `crm.objects.contacts.read`
        * `crm.objects.deals.write`
        * `crm.objects.deals.read`

        Add more only if you need them. Fewer scopes = less blast radius if the token leaks.
      </Step>

      <Step title="Create and copy the token">
        Click **Create app**. Copy the access token (starts with `pat-na1-`). You won't see it again.
      </Step>
    </Steps>

    ## Step 2: Store the Token in Hiveku

    Add it as an environment variable:

    * Go to **Settings > Environment Variables**
    * Add `HUBSPOT_API_KEY` with the token value

    See [Environment Variables](/how-tos/env-vars) for details.

    ## Step 3: Create a Contact from a Form

    <Steps>
      <Step title="Create a workflow">
        Go to **Workflows > New Workflow**. Name it `Form → HubSpot Contact`.
      </Step>

      <Step title="Add a webhook trigger">
        Wire this webhook URL to your site's form submission handler.
      </Step>

      <Step title="Add an HTTP Request action">
        ```
        POST https://api.hubapi.com/crm/v3/objects/contacts
        Headers:
          Authorization: Bearer {{env.HUBSPOT_API_KEY}}
          Content-Type: application/json
        Body:
        {
          "properties": {
            "email": "{{trigger.email}}",
            "firstname": "{{trigger.name}}",
            "company": "{{trigger.company}}"
          }
        }
        ```
      </Step>

      <Step title="Optional: create a deal or task">
        Chain additional HTTP Request actions to the `/crm/v3/objects/deals` or `/crm/v3/objects/tasks` endpoints if you want the contact to land in a pipeline or assign a follow-up.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Reverse Direction: HubSpot → Hiveku

For keeping your site or app in sync when something changes in HubSpot:

<Steps>
  <Step title="Create a HubSpot workflow">
    In HubSpot, go to **Automation > Workflows**. Create a new workflow with whatever trigger matters (contact created, deal stage changed, etc.).
  </Step>

  <Step title="Add a Webhook action">
    Point it at a Hiveku workflow webhook URL.
  </Step>

  <Step title="Handle the payload in Hiveku">
    Your Hiveku workflow receives the HubSpot event and can update your database, send an email, or update the UI.
  </Step>
</Steps>

## Sync Frequency

* **Real-time via webhooks** — best for user-facing updates
* **Periodic batch** — every 15 minutes via a scheduled workflow, good for backfills or bulk updates

<Warning>
  Never write to HubSpot from a workflow that was triggered by HubSpot. That creates a feedback loop — contact updated in HubSpot → webhook → Hiveku workflow → API write back to HubSpot → webhook fires again → infinite loop. Add a flag to skip re-syncs on HubSpot-originated events.
</Warning>

<Tip>
  If you already use HubSpot's native Workflows for automation, keep them there. Use Hiveku Workflows only for things HubSpot can't do — like updating your site content or triggering a deploy.
</Tip>

## Common Patterns

See [Webhook Patterns](/how-tos/webhook-patterns) for standard integration recipes like retries, idempotency, and signature verification.

## Verify It Worked

1. Submit a test form on your site
2. Check the **Workflows > Runs** tab — the run should show a 201 from HubSpot
3. In HubSpot, search contacts for the test email — the contact should appear with the right properties

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The token is wrong, expired, or missing scopes. In HubSpot, go to **Settings > Integrations > Private Apps**, open your app, confirm the token matches what's in `HUBSPOT_API_KEY`. If unsure, regenerate the token and update the env var.
  </Accordion>

  <Accordion title="Duplicate contacts in HubSpot">
    HubSpot deduplicates contacts by email automatically — a POST with an existing email updates rather than creates. If you're seeing dupes, emails are probably different (trailing whitespace, mixed case). Normalize emails before the API call.
  </Accordion>

  <Accordion title="Fields aren't mapping">
    HubSpot uses camelCase internal names that don't match the UI labels. "First Name" in the UI is `firstname` (all lowercase, no underscore) in the API. Check **Settings > Properties** in HubSpot for the exact internal name.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    HubSpot standard tier limits you to 100 requests per 10 seconds. Batch writes with the `/batch/create` endpoint (up to 100 contacts per call), or add retry-with-backoff on 429s.
  </Accordion>

  <Accordion title="Webhook from HubSpot isn't firing">
    In HubSpot, open the workflow and check the **History** tab — is the trigger actually matching? HubSpot Workflows have strict entry criteria. If they're not firing, test by manually enrolling a contact and watching the history.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Webhook Patterns" icon="webhook" href="/how-tos/webhook-patterns">
    Retries, idempotency, and signature verification
  </Card>

  <Card title="CRM Contacts" icon="address-book" href="/how-tos/crm-contacts">
    Manage contacts inside Hiveku alongside HubSpot
  </Card>
</CardGroup>