HubSpot

Authentication

Type	Default	Details
`api_key`	✅	HubSpot Private App Token or legacy API key
`oauth_2`		HubSpot OAuth with CRM scopes

HubSpot OAuth uses tokenAuthMethod: "body" — client credentials are sent in the POST body during token exchange.

Endpoints

Path	Risk	Description
`contacts.get`	read	Fetch a contact by id.
`contacts.getMany`	read	List or paginate contacts.
`contacts.createOrUpdate`	write	Create a new contact (or update if email matches).
`contacts.update`	write	Update an existing contact by id.
`contacts.delete`	destructive	Archive a contact in HubSpot.
`contacts.search`	read	Search contacts via filter groups.

`contacts.get`

Fetch a single contact by ID.

Input: (Zod schema: ContactsGetInputSchema)

Output: (Zod schema: ContactsGetOutputSchema)

`contacts.getMany`

List contacts with pagination.

Input: (Zod schema: ContactsGetManyInputSchema)

Output: (Zod schema: ContactsGetManyOutputSchema)

`contacts.createOrUpdate`

Create a contact or update if the email already exists.

Input: (Zod schema: ContactsCreateOrUpdateInputSchema)

Output: (Zod schema: ContactsCreateOrUpdateOutputSchema)

`contacts.update`

Update an existing contact by ID.

Input: (Zod schema: ContactsUpdateInputSchema)

Output: (Zod schema: ContactsUpdateOutputSchema)

`contacts.delete`

Archive (soft-delete) a contact.

Input: (Zod schema: ContactsDeleteInputSchema)

Output: (Zod schema: ContactsDeleteOutputSchema)

`contacts.search`

Search contacts using filter groups.

Input: (Zod schema: ContactsSearchInputSchema)

Output: (Zod schema: ContactsSearchOutputSchema)

Usage

import { createFabric } from "@fabricorg/integrations";
import { hubspot } from "@fabricorg/integrations/plugins";

const fabric = createFabric({
  plugins: [
    hubspot({
      authType: "api_key",
      key: process.env.HUBSPOT_API_KEY,
      webhookHooks: {
        contacts: {
          created: {
            after: async (ctx, result) => {
              console.log("New contact:", result.data);
            },
          },
        },
      },
    }),
  ],
});

// Search contacts
const results = await fabric.hubspot.api.contacts.search({
  filterGroups: [
    {
      filters: [
        { propertyName: "email", operator: "CONTAINS_TOKEN", value: "@example.com" },
      ],
    },
  ],
});

Webhooks

HubSpot webhooks are dispatched when CRM objects change. The plugin ships a pluginWebhookMatcher that routes requests by x-hubspot-signature-v3 header or subscription type.

Event	Path	Description
Contact created	`contacts.created`	A contact was created in HubSpot.
Contact updated	`contacts.updated`	A contact's properties were updated.
Contact deleted	`contacts.deleted`	A contact was archived.

Webhook payload schema

const HubSpotWebhookPayloadSchema = z.object({
  eventId: z.number(),
  subscriptionId: z.number(),
  portalId: z.number(),
  appId: z.number(),
  occurredAt: z.number(),
  subscriptionType: z.string(),
  attemptNumber: z.number(),
  objectId: z.number(),
  propertyName: z.string().optional(),
  propertyValue: z.string().optional(),
  changeSource: z.string().optional(),
});

Webhook hooks

Use webhookHooks to run code after a webhook is processed:

hubspot({
  webhookHooks: {
    contacts: {
      created: {
        after: async (ctx, result) => {
          await startOnboardingWorkflow(result.data);
        },
      },
    },
  },
});

Entity schema

HubSpot is the reference implementation for plugin entity schemas. Contacts are stored in the entity store for fast lookups and cache-aware queries.

import { HubSpotSchema } from "@fabricorg/integrations/plugins";
// Use with db.hubspot.contacts.* queries

HubSpot

On this page