HubSpot CRM Integration Guide — Connect HubSpot with Laravel, Node.js & Custom APIs

HubSpot CRM integration is powerful out of the box — but its real value comes when you connect it to the rest of your business. Whether you're syncing data from a Laravel app, pushing events from a Node.js backend, automating workflows between HubSpot and WhatsApp, or migrating from Perfex CRM — you need the right integration approach.

This guide covers the complete HubSpot CRM integration process for developers and technical decision-makers. By the end you will know how to authenticate with the HubSpot API, sync contacts and deals, set up webhooks, use custom objects, and connect HubSpot to your existing tech stack.

HubSpot API Authentication — Private Apps vs OAuth

Before making any API calls, you need to authenticate. HubSpot offers two methods:

Private App Tokens (recommended for internal integrations)

Private Apps are the simplest way to authenticate when you are building an integration for your own HubSpot account — not a public app. Go to HubSpot Settings → Integrations → Private Apps → Create a private app. Select the scopes you need (crm.objects.contacts.read, crm.objects.deals.write, etc.) and generate your access token.

Use this token in the Authorization header of every API request:

Authorization: Bearer YOUR_PRIVATE_APP_TOKEN

OAuth 2.0 (for public apps / multi-account integrations)

Use OAuth if you are building an integration that other HubSpot users will install — for example, a HubSpot app on the marketplace or a SaaS product that connects to multiple HubSpot portals.

The OAuth flow: redirect user to HubSpot authorization URL → user grants permission → HubSpot redirects back with an authorization code → exchange code for access token and refresh token → use access token for API calls → refresh when expired.

For most custom integrations (connecting your own app to your own HubSpot), Private App tokens are simpler and sufficient.

Syncing Contacts with the HubSpot REST API

The contacts endpoint is the most commonly used in HubSpot integrations. Here is how to create, update, and retrieve contacts using the v3 API.

Create a contact

Endpoint: POST https://api.hubapi.com/crm/v3/objects/contacts

{ "properties": { "email": "john@example.com", "firstname": "John", "lastname": "Smith", "phone": "+1234567890", "company": "Acme Corp" } }

Update a contact by ID

Endpoint: PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contactId}

{ "properties": { "phone": "+1987654321" } }

Search for a contact by email

Endpoint: POST https://api.hubapi.com/crm/v3/objects/contacts/search

{ "filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "EQ", "value": "john@example.com" }] }] }

Laravel implementation example

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.hubspot.token'))
    ->post('https://api.hubapi.com/crm/v3/objects/contacts', [
        'properties' => [
            'email'     => $user->email,
            'firstname' => $user->first_name,
            'lastname'  => $user->last_name,
            'phone'     => $user->phone,
        ]
    ]);

if ($response->successful()) {
    $hubspotId = $response->json('id');
}

Node.js implementation example

const axios = require('axios');

async function createHubSpotContact(user) {
  const response = await axios.post(
    'https://api.hubapi.com/crm/v3/objects/contacts',
    { properties: { email: user.email, firstname: user.firstName, lastname: user.lastName, phone: user.phone } },
    { headers: { Authorization: `Bearer ${process.env.HUBSPOT_TOKEN}`, 'Content-Type': 'application/json' } }
  );
  return response.data.id;
}

Pro tip: Always search for an existing contact by email before creating a new one. Creating duplicates is the most common mistake in HubSpot integrations and is difficult to clean up at scale.

Setting Up HubSpot Webhooks

Webhooks let HubSpot notify your application instantly when something changes in the CRM — a contact is created, a deal stage changes, a form is submitted.

Outbound webhooks from HubSpot Workflows

Go to HubSpot → Automation → Workflows → create or edit a workflow → add action → Send a webhook. Configure the Method (POST), your Webhook URL, and Authentication type. HubSpot will POST a JSON payload to your URL every time the workflow trigger fires.

Receiving HubSpot webhooks in Laravel

Route::post('/api/hubspot/webhook', [HubSpotWebhookController::class, 'handle']);

public function handle(Request $request)
{
    $payload = $request->all();
    foreach ($payload as $event) {
        $eventType = $event['subscriptionType'];
        $objectId  = $event['objectId'];
        match ($eventType) {
            'contact.creation'    => $this->handleNewContact($objectId),
            'deal.propertyChange' => $this->handleDealUpdate($objectId, $event),
            default               => null,
        };
    }
    return response()->json(['status' => 'received']);
}

Important: HubSpot webhook delivery is not guaranteed to be in order. Always check the event timestamp and handle out-of-order delivery gracefully in your application.

HubSpot Custom Objects

Custom objects let you store data that doesn't fit HubSpot's standard objects. Available on Professional and Enterprise plans.

Common use cases: properties (real estate), courses (education), vehicles (automotive), projects (agencies), bookings (hospitality).

Create a custom object schema via API

POST https://api.hubapi.com/crm/v3/schemas

{ "name": "Project", "labels": { "singular": "Project", "plural": "Projects" }, "primaryDisplayProperty": "project_name", "properties": [ { "name": "project_name", "label": "Project Name", "type": "string", "fieldType": "text" }, { "name": "project_status", "label": "Status", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Active", "value": "active" }, { "label": "On Hold", "value": "on_hold" }, { "label": "Completed", "value": "completed" } ] }, { "name": "budget", "label": "Budget", "type": "number", "fieldType": "number" } ], "associatedObjects": ["CONTACT", "COMPANY", "DEAL"] }

Once created, you can create, read, update, and delete Project records via /crm/v3/objects/projects (using the plural name).

Connecting HubSpot with WhatsApp

One of the most requested integrations — sending WhatsApp messages triggered by HubSpot workflow events and capturing incoming WhatsApp conversations as HubSpot contacts.

Architecture: HubSpot Workflow trigger → Webhook → Your Node.js/Laravel middleware → WhatsApp Business API

When a deal reaches the Proposal Sent stage in HubSpot: (1) HubSpot workflow fires a webhook to your server, (2) your server reads the contact phone number from the payload, (3) your server sends a WhatsApp message via Twilio or UltraMsg API, (4) delivery status is written back to HubSpot contact via API.

Incoming WhatsApp to HubSpot: When a customer sends a WhatsApp message — the WhatsApp Business API sends a webhook to your server, your server searches HubSpot for the phone number, if found creates a note on the contact record, if not found creates a new contact in HubSpot.

This is a full integration pattern we build regularly at Websicon. Learn more about our WhatsApp chatbot and integration services.

Migrating from Perfex CRM or Rise CRM to HubSpot

If you are moving to HubSpot from Perfex CRM or Rise CRM, here is the migration approach we follow:

Step 1 — Data audit: Export all data from Perfex/Rise: clients, contacts, projects, invoices, leads, notes, tickets. Identify which data maps to HubSpot standard objects and which needs custom objects.

Step 2 — Field mapping: Map Perfex/Rise fields to HubSpot properties. Create custom properties in HubSpot for any fields that don't have a standard equivalent.

Step 3 — Data cleansing: Deduplicate contacts by email. Standardise phone number formats. Remove test records and incomplete entries.

Step 4 — Import: Use HubSpot's import tool for bulk CSV imports of contacts and companies. Use the API for deals, notes, and custom objects where CSV import is not supported.

Step 5 — Validation: Spot-check 50–100 records across all object types. Verify associations (contacts linked to companies, deals linked to contacts). Confirm custom field values transferred correctly.

Step 6 — Cutover: Run both systems in parallel for 1–2 weeks. Set Perfex/Rise to read-only. Switch fully to HubSpot once validation is complete.

The most common migration issue is phone number format inconsistency — fix this in Step 3 before importing.

Frequently Asked Questions