HubSpot App Integration

Purpose and Scope

The HubSpot app package is the repository home for Dub's HubSpot marketplace integration. Its job is not to implement the whole Dub conversion pipeline locally; instead, it defines the HubSpot application metadata, OAuth permissions, webhook subscriptions, and developer workflow needed to connect HubSpot CRM activity to Dub. In user-facing terms, the integration lets teams track HubSpot lead and deal events as Dub conversion activity, which is especially useful for B2B SaaS teams using HubSpot as their CRM while relying on Dub for link attribution, partner programs, and commissions.

Sources: packages/hubspot-app/README.md, packages/hubspot-app/src/app/app-hsmeta.json, packages/hubspot-app/src/app/webhooks/webhooks-hsmeta.json

The package describes the app as Dub Partners in HubSpot metadata and explains its product intent directly in the app description: track HubSpot leads and deal changes, then auto-generate partner commissions on Dub. That wording matters because this integration is aligned with affiliate and partner attribution rather than generic CRM synchronization. Official Dub integration docs also frame HubSpot around conversion tracking, including meeting bookings and deal creation or closed-won activity as lead and sale conversion events, so developers should think of this package as the HubSpot-side registration layer for a larger Dub conversions workflow.

Sources: packages/hubspot-app/src/app/app-hsmeta.json

Relevant Source Files

• packages/hubspot-app/README.md — Introduces the Dub HubSpot App package and lists the HubSpot CLI commands used for development, upload, dependency installation, feature creation, and account inspection.
• packages/hubspot-app/package.json — Declares the package name, private package status, module type, HubSpot CLI dependency, hs script, TypeScript-related development dependencies, Node engine, and MIT package license.
• packages/hubspot-app/src/app/app-hsmeta.json — Defines the HubSpot app metadata, marketplace distribution, OAuth redirect URLs, required scopes, permitted HubSpot API fetch origin, and support links.
• packages/hubspot-app/src/app/webhooks/webhooks-hsmeta.json — Defines the HubSpot webhook extension, Dub webhook target URL, concurrency setting, and CRM object subscriptions for contacts and deals.

Package and Developer Workflow

The package is named dub-hubspot-app, is marked private, and exposes a single script named hs that delegates to the HubSpot CLI. That makes the package a focused integration workspace rather than a published npm library. Its direct runtime dependency is @hubspot/cli, while TypeScript, tsup, rimraf, and Node types are development dependencies. The package declares type module and supports Node versions greater than or equal to 14, so contributors should run commands in a modern Node environment while treating HubSpot CLI behavior as the primary interface.

Sources: packages/hubspot-app/package.json

Local development begins with installing repository dependencies, then using the HubSpot CLI through pnpm. The README shows commands for uploading the project to a HubSpot account, starting a development environment, installing project dependencies, adding features to the app, and listing connected accounts. The important detail is that these are HubSpot project lifecycle commands, not Dub web app commands. A contributor validating metadata changes should use the CLI to sync the package to a HubSpot test account before expecting webhook or OAuth behavior to be active.

Sources: packages/hubspot-app/README.md, packages/hubspot-app/package.json

# Install dependencies
pnpm install
 
# Upload the project to a HubSpot account
pnpm hs project upload --account=<account-id>
 
# Set up a test environment and start local development
pnpm hs project dev
 
# Install all project dependencies
pnpm hs project install-deps
 
# Add a new feature to the app
pnpm hs project add
 
# List all connected HubSpot accounts
pnpm hs account list

HubSpot App Metadata

The main app metadata file identifies the HubSpot app with uid dub and type app. Its config names the app Dub Partners, marks distribution as marketplace, and provides the public product description used by HubSpot. This file is the source of truth for the HubSpot-facing application identity, so changes here affect how the app is represented in HubSpot rather than how Dub's internal API handlers are implemented. When reviewing changes, check whether the app name, description, distribution, and support URLs still match the intended public integration experience.

Sources: packages/hubspot-app/src/app/app-hsmeta.json

Authentication is declared as OAuth. The metadata allows two redirect URLs: the production Dub callback at https://app.dub.co/api/hubspot/callback and the preview callback at https://preview.dub.co/api/hubspot/callback. Required scopes include oauth, contact read and write access, deal read access, and contact schema write access. There are no optional or conditionally required scopes. The package also restricts permitted fetch URLs to https://api.hubapi.com, which keeps the HubSpot app declaration aligned with calling HubSpot's public API rather than arbitrary external services.

Sources: packages/hubspot-app/src/app/app-hsmeta.json

Webhook Subscriptions and Event Flow

The webhook metadata is the HubSpot-side bridge that tells HubSpot which CRM changes should be delivered to Dub. It declares a webhooks extension with uid dub-webhooks and points HubSpot at https://app.dub.co/api/hubspot/webhook. The maxConcurrentRequests setting is 10, which gives HubSpot permission to deliver multiple webhook requests concurrently while still bounding delivery pressure. This package therefore defines the event ingress contract: HubSpot emits CRM lifecycle events, and Dub receives them through a web endpoint that can interpret them as conversion or partner-program activity.

Sources: packages/hubspot-app/src/app/webhooks/webhooks-hsmeta.json

Four CRM object subscriptions are active. Contact creation is subscribed, deal creation is subscribed, dealstage property changes on deals are subscribed, and lifecyclestage property changes on contacts are subscribed. Those choices mirror the product problem described in the integration docs: a new contact can become a lead signal, a new deal can indicate commercial progression, and changes in deal stage or lifecycle stage can represent qualification, conversion, or closed-won milestones. The metadata does not assign those business meanings itself; it ensures HubSpot delivers the raw CRM events to Dub for downstream handling.

Sources: packages/hubspot-app/src/app/webhooks/webhooks-hsmeta.json

Compact Reference

Implementation Notes and Review Checklist

Because this package is primarily declarative, most changes should be reviewed as integration-contract changes. A new OAuth scope changes what HubSpot users are asked to authorize. A new redirect URL changes where OAuth completion can land. A new subscription changes which CRM events Dub receives. A new permitted URL changes the network surface declared to HubSpot. These edits should be treated with the same care as API changes, because they affect installation, marketplace review, user trust, and production event delivery even when no TypeScript application code changes in this package.

Sources: packages/hubspot-app/src/app/app-hsmeta.json, packages/hubspot-app/src/app/webhooks/webhooks-hsmeta.json

A practical validation pass should start by checking the package metadata, then uploading or developing the project with the HubSpot CLI against a test account. Confirm that the app installs with the expected OAuth prompt, that the callback URL matches the environment being tested, and that subscribed CRM events are visible to Dub's webhook endpoint. If the work is related to conversion attribution, pair this page with the Track API and conversion-tracking documentation so the HubSpot event vocabulary is connected to Dub's lead, sale, and partner commission workflows rather than reviewed in isolation.