HubSpot CRM Integration GuideContacts, Deals, Workflows, Webhooks, and Automation

flowchart TD
  FE["Frontend\nReact / Next.js / Vue"] -- "User actions\n(form submit, upgrade)" --> API["Your Backend API"]
  API -- "Create/Update contact\nCreate/Update deal" --> HS["HubSpot API\nv3 REST + OAuth 2.0"]
  HS -- "CRM Data Layer\nContacts / Deals / Companies" --> DB_HS[("HubSpot CRM")]
  HS -- "Webhooks\n(contact.creation, deal.stageChange)" --> WH["Webhook Handler\n(your backend)"]
  WH -- "Queue event" --> Q["Message Queue\nBullMQ / SQS / Redis"]
  Q -- "Process event" --> WORKER["Background Worker"]
  WORKER -- "Update application state" --> DB[("Your Database")]
  API -- "Cache contact lookups" --> CACHE["Redis Cache"]

import { useState } from "react";

interface ContactPayload {
  email: string;
  firstName: string;
  lastName: string;
  company?: string;
}

export function useHubSpotContact() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function createContact(data: ContactPayload) {
    setLoading(true);
    setError(null);
    try {
      const res = await fetch("/api/crm/contacts", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
      });
      if (!res.ok) throw new Error(await res.text());
      return await res.json();
    } catch (err: unknown) {
      setError(err instanceof Error ? err.message : "Unknown error");
    } finally {
      setLoading(false);
    }
  }

  return { createContact, loading, error };
}

"use server";

import { Client } from "@hubspot/api-client";

const hs = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });

export async function createHubSpotContact(formData: FormData) {
  const email = formData.get("email") as string;
  const firstname = formData.get("firstName") as string;
  const lastname = formData.get("lastName") as string;

  const existing = await hs.crm.contacts.searchApi.doSearch({
    filterGroups: [{
      filters: [{ propertyName: "email", operator: "EQ", value: email }],
    }],
    properties: ["email", "firstname"],
    limit: 1,
    after: 0,
    sorts: [],
  });

  if (existing.total > 0) return { id: existing.results[0].id, created: false };

  const contact = await hs.crm.contacts.basicApi.create({
    properties: { email, firstname, lastname },
    associations: [],
  });

  return { id: contact.id, created: true };
}

import { ref } from "vue";

export function useHubSpot() {
  const loading = ref(false);
  const error = ref<string | null>(null);

  async function syncContact(payload: {
    email: string;
    firstName: string;
    lastName: string;
  }) {
    loading.value = true;
    error.value = null;
    try {
      const res = await fetch("/api/crm/contacts", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      });
      if (!res.ok) throw new Error("CRM sync failed");
      return await res.json();
    } catch (e: unknown) {
      error.value = e instanceof Error ? e.message : "Error";
    } finally {
      loading.value = false;
    }
  }

  return { syncContact, loading, error };
}

import { Injectable } from "@angular/core";
import { HttpClient } from "@angular/common/http";
import { catchError, retry, throwError } from "rxjs";

@Injectable({ providedIn: "root" })
export class CrmService {
  constructor(private http: HttpClient) {}

  createContact(payload: { email: string; firstName: string; lastName: string }) {
    return this.http
      .post("/api/crm/contacts", payload)
      .pipe(retry(2), catchError((err) => throwError(() => err)));
  }

  updateDeal(dealId: string, stage: string) {
    return this.http
      .patch(`/api/crm/deals/${dealId}`, { stage })
      .pipe(retry(2), catchError((err) => throwError(() => err)));
  }
}

import type { Actions } from "./$types";

export const actions: Actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    await fetch("https://your-api/crm/contacts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email: data.get("email"),
        firstName: data.get("firstName"),
      }),
    });
    return { success: true };
  },
};

import type { APIRoute } from "astro";

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  await fetch("https://your-api/crm/contacts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};

import { Client } from "@hubspot/api-client";

const client = new Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
  numberOfApiCallRetries: 3,
});

export async function upsertContact(email: string, props: Record<string, string>) {
  try {
    const search = await client.crm.contacts.searchApi.doSearch({
      filterGroups: [{
        filters: [{ propertyName: "email", operator: "EQ", value: email }],
      }],
      properties: ["email", "hs_object_id"],
      limit: 1,
      after: 0,
      sorts: [],
    });

    if (search.total > 0) {
      return client.crm.contacts.basicApi.update(
        search.results[0].id,
        { properties: props, associations: [] }
      );
    }

    return client.crm.contacts.basicApi.create({
      properties: { email, ...props },
      associations: [],
    });
  } catch (err: unknown) {
    console.error("HubSpot upsertContact failed", err);
    throw err;
  }
}

import { Injectable, Logger, OnModuleInit } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { Client } from "@hubspot/api-client";

@Injectable()
export class HubSpotService implements OnModuleInit {
  private client: Client;
  private readonly logger = new Logger(HubSpotService.name);

  constructor(private config: ConfigService) {}

  onModuleInit() {
    this.client = new Client({
      accessToken: this.config.get<string>("HUBSPOT_ACCESS_TOKEN"),
      numberOfApiCallRetries: 3,
    });
  }

  async createContact(email: string, properties: Record<string, string>) {
    this.logger.log(`Creating HubSpot contact: ${email}`);
    return this.client.crm.contacts.basicApi.create({
      properties: { email, ...properties },
      associations: [],
    });
  }

  async updateDealStage(dealId: string, stage: string) {
    this.logger.log(`Updating deal ${dealId} to stage ${stage}`);
    return this.client.crm.deals.basicApi.update(dealId, {
      properties: { dealstage: stage },
      associations: [],
    });
  }
}

import httpx
import os
from typing import Optional

HUBSPOT_BASE = "https://api.hubapi.com"
TOKEN = os.getenv("HUBSPOT_ACCESS_TOKEN")

async def upsert_contact(email: str, properties: dict) -> dict:
    headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
    async with httpx.AsyncClient(timeout=10.0) as client:
        # Search for existing contact
        search_res = await client.post(
            f"{HUBSPOT_BASE}/crm/v3/objects/contacts/search",
            headers=headers,
            json={"filterGroups": [{"filters": [
                {"propertyName": "email", "operator": "EQ", "value": email}
            ]}], "properties": ["email"], "limit": 1},
        )
        search_res.raise_for_status()
        results = search_res.json().get("results", [])

        if results:
            contact_id = results[0]["id"]
            res = await client.patch(
                f"{HUBSPOT_BASE}/crm/v3/objects/contacts/{contact_id}",
                headers=headers,
                json={"properties": properties},
            )
        else:
            res = await client.post(
                f"{HUBSPOT_BASE}/crm/v3/objects/contacts",
                headers=headers,
                json={"properties": {"email": email, **properties}},
            )

        res.raise_for_status()
        return res.json()

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class HubSpotService
{
    private string $baseUrl = 'https://api.hubapi.com';
    private string $token;

    public function __construct()
    {
        $this->token = config('services.hubspot.token');
    }

    public function upsertContact(string $email, array $properties): array
    {
        $search = Http::withToken($this->token)
            ->post("{$this->baseUrl}/crm/v3/objects/contacts/search", [
                'filterGroups' => [[
                    'filters' => [['propertyName' => 'email', 'operator' => 'EQ', 'value' => $email]],
                ]],
                'properties' => ['email'],
                'limit' => 1,
            ])->throw()->json();

        if (!empty($search['results'])) {
            $id = $search['results'][0]['id'];
            return Http::withToken($this->token)
                ->patch("{$this->baseUrl}/crm/v3/objects/contacts/{$id}", ['properties' => $properties])
                ->throw()->json();
        }

        return Http::withToken($this->token)
            ->post("{$this->baseUrl}/crm/v3/objects/contacts", [
                'properties' => array_merge(['email' => $email], $properties),
            ])->throw()->json();
    }
}

import requests
import os

BASE = "https://api.hubapi.com"
HEADERS = {
    "Authorization": f"Bearer {os.getenv('HUBSPOT_ACCESS_TOKEN')}",
    "Content-Type": "application/json",
}

def upsert_contact(email: str, properties: dict) -> dict:
    search = requests.post(
        f"{BASE}/crm/v3/objects/contacts/search",
        headers=HEADERS,
        json={"filterGroups": [{"filters": [
            {"propertyName": "email", "operator": "EQ", "value": email}
        ]}], "properties": ["email"], "limit": 1},
    )
    search.raise_for_status()
    results = search.json().get("results", [])

    if results:
        contact_id = results[0]["id"]
        res = requests.patch(
            f"{BASE}/crm/v3/objects/contacts/{contact_id}",
            headers=HEADERS,
            json={"properties": properties},
        )
    else:
        res = requests.post(
            f"{BASE}/crm/v3/objects/contacts",
            headers=HEADERS,
            json={"properties": {"email": email, **properties}},
        )

    res.raise_for_status()
    return res.json()

package hubspot

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

const baseURL = "https://api.hubapi.com"

func authHeader() string {
    return "Bearer " + os.Getenv("HUBSPOT_ACCESS_TOKEN")
}

func CreateContact(email string, properties map[string]string) error {
    props := map[string]interface{}{"email": email}
    for k, v := range properties {
        props[k] = v
    }
    body, _ := json.Marshal(map[string]interface{}{"properties": props})
    req, _ := http.NewRequest("POST", baseURL+"/crm/v3/objects/contacts", bytes.NewBuffer(body))
    req.Header.Set("Authorization", authHeader())
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode >= 400 {
        return fmt.Errorf("hubspot error: %d", resp.StatusCode)
    }
    return nil
}

@Service
public class HubSpotService {
    private final WebClient webClient;

    public HubSpotService(@Value("${hubspot.access-token}") String token) {
        this.webClient = WebClient.builder()
            .baseUrl("https://api.hubapi.com")
            .defaultHeader("Authorization", "Bearer " + token)
            .defaultHeader("Content-Type", "application/json")
            .build();
    }

    public Mono<Map> createContact(String email, Map<String, String> properties) {
        Map<String, Object> props = new HashMap<>(properties);
        props.put("email", email);
        return webClient.post()
            .uri("/crm/v3/objects/contacts")
            .bodyValue(Map.of("properties", props))
            .retrieve()
            .onStatus(HttpStatusCode::isError, res ->
                Mono.error(new RuntimeException("HubSpot error: " + res.statusCode())))
            .bodyToMono(Map.class);
    }
}

public class HubSpotService
{
    private readonly HttpClient _http;
    private readonly ILogger<HubSpotService> _logger;

    public HubSpotService(HttpClient http, ILogger<HubSpotService> logger)
    {
        _http = http;
        _logger = logger;
    }

    public async Task<JsonElement> CreateContactAsync(string email, Dictionary<string, string> properties)
    {
        properties["email"] = email;
        var payload = new { properties };
        var res = await _http.PostAsJsonAsync("/crm/v3/objects/contacts", payload);
        res.EnsureSuccessStatusCode();
        return await res.Content.ReadFromJsonAsync<JsonElement>();
    }
}

use reqwest::Client;
use serde_json::{json, Value};
use std::collections::HashMap;

pub async fn create_contact(
    email: &str,
    properties: HashMap<&str, &str>,
    token: &str,
) -> Result<Value, reqwest::Error> {
    let mut props = json!({ "email": email });
    for (k, v) in &properties {
        props[k] = json!(v);
    }
    let client = Client::new();
    let res = client
        .post("https://api.hubapi.com/crm/v3/objects/contacts")
        .bearer_auth(token)
        .json(&json!({ "properties": props }))
        .send()
        .await?
        .error_for_status()?
        .json::<Value>()
        .await?;
    Ok(res)
}

import { Client } from "@hubspot/api-client";
import { encrypt, decrypt } from "../lib/crypto";

const hs = new Client({});

// Step 1: Build authorization URL
export function getAuthUrl(state: string) {
  return hs.oauth.getAuthorizationUrl(
    process.env.HUBSPOT_CLIENT_ID!,
    process.env.HUBSPOT_REDIRECT_URI!,
    "crm.objects.contacts.write crm.objects.deals.write",
    state
  );
}

// Step 2: Exchange code for tokens (in callback handler)
export async function handleOAuthCallback(code: string, accountId: string) {
  const tokens = await hs.oauth.tokensApi.createToken(
    "authorization_code",
    code,
    process.env.HUBSPOT_REDIRECT_URI!,
    process.env.HUBSPOT_CLIENT_ID!,
    process.env.HUBSPOT_CLIENT_SECRET!
  );
  // Store encrypted tokens in your database
  await db.hubspotTokens.upsert({
    where: { accountId },
    update: {
      accessToken: encrypt(tokens.accessToken),
      refreshToken: encrypt(tokens.refreshToken!),
      expiresAt: new Date(Date.now() + tokens.expiresIn * 1000),
    },
    create: {
      accountId,
      accessToken: encrypt(tokens.accessToken),
      refreshToken: encrypt(tokens.refreshToken!),
      expiresAt: new Date(Date.now() + tokens.expiresIn * 1000),
    },
  });
}

// Step 3: Auto-refresh before API calls
export async function getClientForAccount(accountId: string) {
  const record = await db.hubspotTokens.findUnique({ where: { accountId } });
  if (!record) throw new Error("No HubSpot token for account");

  if (new Date() >= record.expiresAt) {
    const refreshed = await hs.oauth.tokensApi.createToken(
      "refresh_token",
      undefined,
      undefined,
      process.env.HUBSPOT_CLIENT_ID!,
      process.env.HUBSPOT_CLIENT_SECRET!,
      decrypt(record.refreshToken)
    );
    await db.hubspotTokens.update({
      where: { accountId },
      data: {
        accessToken: encrypt(refreshed.accessToken),
        expiresAt: new Date(Date.now() + refreshed.expiresIn * 1000),
      },
    });
    return new Client({ accessToken: refreshed.accessToken });
  }

  return new Client({ accessToken: decrypt(record.accessToken) });
}

import crypto from "crypto";
import { Request, Response } from "express";

function verifyHubSpotSignature(req: Request): boolean {
  const signature = req.headers["x-hubspot-signature-v3"] as string;
  const timestamp = req.headers["x-hubspot-request-timestamp"] as string;
  if (!signature || !timestamp) return false;

  // Reject requests older than 5 minutes
  if (Math.abs(Date.now() - parseInt(timestamp)) > 300_000) return false;

  const rawBody = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha256", process.env.HUBSPOT_CLIENT_SECRET!)
    .update(req.method + req.originalUrl + rawBody + timestamp)
    .digest("base64");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

export async function hubspotWebhookHandler(req: Request, res: Response) {
  if (!verifyHubSpotSignature(req)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Respond immediately   process asynchronously
  res.status(200).json({ received: true });

  const events: Array<{ subscriptionType: string; objectId: number; propertyName?: string; propertyValue?: string }> = req.body;

  for (const event of events) {
    await queue.add("hubspot-event", event, {
      attempts: 5,
      backoff: { type: "exponential", delay: 2000 },
    });
  }
}

import { Worker, Job } from "bullmq";
import { redis } from "../lib/redis";

const worker = new Worker(
  "hubspot-event",
  async (job: Job) => {
    const { subscriptionType, objectId, propertyName, propertyValue } = job.data;

    // Idempotency check
    const key = `hs-event:${subscriptionType}:${objectId}:${job.id}`;
    const processed = await redis.get(key);
    if (processed) return;

    switch (subscriptionType) {
      case "contact.creation":
        await handleContactCreated(objectId);
        break;
      case "deal.propertyChange":
        if (propertyName === "dealstage") {
          await handleDealStageChange(objectId, propertyValue!);
        }
        break;
    }

    await redis.set(key, "1", "EX", 86400); // TTL 24h
  },
  { connection: redis, concurrency: 10 }
);

worker.on("failed", (job, err) => {
  console.error(`HubSpot event job ${job?.id} failed:`, err.message);
});

import { upsertContact, createDeal, updateDeal } from "../lib/hubspot";

export async function handleCustomerUpgrade(userId: string, newPlan: string, mrr: number) {
  const user = await db.users.findUnique({ where: { id: userId } });

  // Update contact lifecycle stage
  await upsertContact(user.email, {
    lifecyclestage: "customer",
    current_plan: newPlan,
    mrr: String(mrr),
  });

  // Check for existing deal
  const existingDeal = await db.hubspotDeals.findFirst({ where: { userId } });

  if (existingDeal) {
    await updateDeal(existingDeal.hubspotId, {
      dealstage: "closedwon",
      amount: String(mrr * 12),
      closedate: String(Date.now()),
    });
  } else {
    const deal = await createDeal({
      dealname: `${user.email}   ${newPlan} upgrade`,
      pipeline: "default",
      dealstage: "closedwon",
      amount: String(mrr * 12),
      closedate: String(Date.now()),
    });
    await db.hubspotDeals.create({ data: { userId, hubspotId: deal.id } });
  }
}

import { Client } from "@hubspot/api-client";

const hs = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });

export async function logTicketAsCrmActivity(
  contactId: string,
  ticketSubject: string,
  ticketBody: string
) {
  await hs.crm.objects.notes.basicApi.create({
    properties: {
      hs_note_body: `Support ticket: ${ticketSubject}\n\n${ticketBody}`,
      hs_timestamp: String(Date.now()),
    },
    associations: [{
      to: { id: contactId },
      types: [{ associationCategory: "HUBSPOT_DEFINED", associationTypeId: 202 }],
    }],
  });
}