Payload HubSpot Plugin

A PayloadCMS plugin for HubSpot integration - view and manage HubSpot forms directly in your Payload admin dashboard.

Features

• 📊 Dashboard Overview: View all your HubSpot forms with key metrics directly in your Payload admin dashboard
• 📈 Form Analytics: See comprehensive form metrics including views, submissions, conversion rates, click-through rates, and interactions
• 🔄 Auto-Sync: Forms are automatically synced with HubSpot on server startup
• 📋 Form Management: Create and manage HubSpot form connections in Payload
• 🔌 Easy Integration: Simple configuration with minimal setup required
• ⚡ Smart Caching: 1-hour cache with refresh capability for optimal performance

Installation

# npm
npm install payload-hubspot

# yarn
yarn add payload-hubspot

# pnpm
pnpm add payload-hubspot

Usage

Basic Setup

Add the plugin to your Payload config:

import { buildConfig } from 'payload'
import { payloadHubspot } from 'payload-hubspot'

export default buildConfig({
  // ... your existing config
  plugins: [
    payloadHubspot({
      apiKey: process.env.HUBSPOT_API_KEY, // Your HubSpot API key
    }),
  ],
})

Environment Variables

Add these to your .env file:

HUBSPOT_PORTAL_ID=your-hubspot-portal-id
HUBSPOT_API_KEY=your-hubspot-api-key

Configuration Options

The plugin accepts the following options:

type PayloadHubspotConfig = {
  apiKey?: string // Your HubSpot API key (can also be set via env var)
  collections?: Partial<Record<CollectionSlug, true>> // Collections to add HubSpot fields to
  disabled?: boolean // Set to true to disable the plugin functionality
  disableDashboard?: boolean // Set to true to disable the dashboard component
}

Full Example

import { buildConfig } from 'payload'
import { payloadHubspot } from 'payload-hubspot'

export default buildConfig({
  // ... your existing config
  plugins: [
    payloadHubspot({
      apiKey: process.env.HUBSPOT_API_KEY,
      collections: {
        pages: true,
        posts: true,
      },
      // Optional: disable dashboard component
      disableDashboard: false,
    }),
  ],
})

Features

Dashboard Component

The plugin adds a dashboard component to the HubSpot Forms collection that displays:

• Total number of forms
• Total form views
• Total form submissions
• Average conversion rate
• A sortable table of all forms with comprehensive metrics including:
  • Form views and submissions
  • Conversion rates and click-through rates
  • Form interactions and submission rates
  • Copy-to-clipboard functionality for form IDs

HubSpot Forms Collection

The plugin creates a hubspot-forms collection in your Payload CMS with the following fields:

• formId: The HubSpot form GUID (required, unique)
• name: The form name (automatically synced from HubSpot, read-only)

The collection includes automatic hooks that:

• Sync form names from HubSpot when formId is updated
• Update existing forms on server startup (doesn't create new ones automatically)

API Endpoints

The plugin adds the following API endpoints:

• GET /api/hubspot/forms: Returns a list of all HubSpot forms with comprehensive statistics
  • Add ?refresh=true to force a refresh of the 1-hour cache
• GET /api/my-plugin-endpoint: Custom endpoint (example implementation)

Analytics Data

Each form includes the following analytics:

• views: Total form views
• submissions: Total form submissions
• conversionRate: Submissions per form view (when <= 1)
• clickThroughRate: Click-through rate per form view
• interactions: Total form interactions
• submissionRate: Submissions per click-through
• nonContactSubmissions: Non-contact form submissions

Development

Setup

# Clone the repository
git clone https://github.com/Brightscout/payload-hubspot.git
cd payload-hubspot

# Install dependencies
pnpm install

# Start the development server
pnpm dev

Building

pnpm build

Testing

pnpm test

Requirements

• Node.js: ^18.20.2 || >=20.9.0
• PayloadCMS: ^3.29.0
• Package Manager: pnpm ^9 || ^10

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• GitHub Issues
• Package Homepage