Quartz 5

Zapier CLI & HubSpot Workflows Integration Architecture

Properties1
tagsdogwizard--crm--zapier--hubspot

3 min read

Zapier CLI & HubSpot Native Workflows Dual-Engine Architecture

This log captures the architectural design for integrating PocketSuite with HubSpot CRM (Sales Hub Pro) for The Dog Wizard franchise, using the Zapier Platform CLI for ingestion and HubSpot Native Workflows for downstream database automation.

🚀 The Core Philosophy: “Single-Action Ingest, Native Orchestration”

To keep operations resilient, low-latency, and cost-efficient, we divide the data flow into two distinct stages:

  1. Ingestion & Normalization (Zapier Platform CLI): Runs as a custom-coded, version-controlled developer app. Its sole job is to capture PocketSuite webhook events, normalize payload fields (specifically phone numbers to strict E.164 formatting), and land the Contact record into HubSpot.
  2. Downstream Database Automation (HubSpot Native Workflows): HubSpot handles all CRM-native activities (such as geographic assignment via custom Zip Code objects, spawning Lead records in the Prospecting Workspace, and advancing Lead stages based on Call/SMS activities).

🛠️ Stage 1: The Zapier Platform CLI Engine

By utilizing the newly installed Zapier Platform CLI on The Box (The Engine), we bypass the heavy visual task-chaining that inflates monthly billing in Zapier.

📁 Directory Layout

The custom Zapier app will reside in the workspace:

~/projects/03_clients/dogwizard/drag-migration/zapier-app/
├── package.json          # Dependency definition
├── index.js              # Entry point registering triggers, creates, and searches
├── triggers/
│   └── new_client_webhook.js # Catch raw webhooks from PocketSuite
├── creates/
│   └── upsert_normalized_contact.js # Custom action to search & upsert contact
└── test/
    └── integration.test.js   # Jest test suite for local verification

🎯 Key Benefits of the Zapier CLI App:

  • Zero-Task Helper Overhead: Standard Zapier apps require separate “Formatter” tasks and “Find Contact” steps, which eat up 3-4 tasks per run. In the custom Node.js app, we run formatting and search-and-upsert inside a single custom step, saving hundreds of dollars a month.
  • Version Controlled & Git-Driven: The entire integration codebase is reviewable, diffable, and deployable via terminal commands (zapier push).
  • Strict E.164 Phone Normalization: We normalize phone inputs in raw JavaScript before hitting HubSpot: 
    function formatToE164(phone) {
  const cleaned = ('' + phone).replace(/\D/g, '');
  if (cleaned.length === 10) return `+1${cleaned}`;
  if (cleaned.length === 11 && cleaned.startsWith('1')) return `+${cleaned}`;
  return phone; // fallback
}
    This matches the precise format used by the Quo (OpenPhone) integration, ensuring timeline events auto-match.

⚡ Stage 2: HubSpot Native Workflows

Once the contact is created and updated by the Zapier CLI, HubSpot’s native workflows take over to run internal operations.

🗺️ 1. Geographic Zip-Code Routing

  • Trigger: Contact Zip/Postal Code is updated and known.
  • Traversal Logic:
    1. Look up the custom Zip Codes object record matching the contact’s zip.
    2. Traverse association to the custom Territories object record.
    3. Traverse association to the franchise branch Company record.
    4. Auto-associate the Contact with the franchise Company record.
  • Benefit: Zero-maintenance, runs instantly on HubSpot’s core database with no API roundtrips.

🧭 2. Lead Object Creation (Prospecting Workspace)

  • Trigger: Contact PS Client ID is known.
  • Action: Spawn a Lead record under the Leads Object (Sales Hub Pro).
  • Association: Auto-associate the Lead with the Contact and the geographically resolved franchise branch Company record.
  • Stage: Initialize to New.

🔄 3. Lead Stage Progression (Activity-Driven)

  • Lead Stage: Attempting
    • Trigger: SMS activity registered on the Contact (via Quo) OR PS Outreach Sent = True.
  • Lead Stage: Connected
    • Trigger: Call activity logged on Contact (via Quo) OR PS Connection Established = True.
  • Lead Stage: Qualified
    • Trigger: Evaluation booking registered in PocketSuite (writing to HubSpot Contact).

🧭 Architectural Advantage

This dual-engine architecture combines the flexibility of standard developer tools (Zapier CLI) with the robust, zero-cost scaling of enterprise SaaS workflows (HubSpot Sales Hub Pro), ensuring a fast, clean, and highly professional CRM migration.

Graph View

Backlinks