Skip to content
threada Docs

HubSpot App Marketplace

This guide defines the HubSpot App Marketplace path after Slack Marketplace, the Zapier public integration scaffold, Microsoft Teams Store scoping, Google Workspace Marketplace scoping, Atlassian Marketplace scoping, and Zendesk Marketplace scoping. It is a design and launch-control document, not evidence that a HubSpot App Marketplace app has been built or approved.

Current Status

HubSpot App Marketplace is planned as a public store follow-on. Threada already has governed HubSpot action proposal payloads for hubspot_upsert_contact, hubspot_upsert_deal, and hubspot_update_ticket in the public API action model. A private HubSpot App Marketplace package scaffold exists at packages/hubspot-marketplace-app. It generates a Marketplace-distributed OAuth app-hsmeta.json, listing metadata, asset checklist, and readiness blockers. Public setup/support guidance now lives in HubSpot setup and support.

The shared marketplace OAuth install path now supports HubSpot as a contact-scoped runtime integration. The install callback stores the tenant credential in Secret Manager, uses HubSpot OAuth 2026-03 token introspection to discover the authorized portal hub_id, and upserts an enabled portal-keyed HubSpot runtime integration for contact create/update actions. The runtime adapter enforces the marketplace_allowed_action_types metadata and revalidates the HubSpot CRM API endpoint before reading credentials, so marketplace HubSpot installs cannot execute deal or ticket actions unless a later app version grants and documents broader scopes. This is runtime implementation evidence, not HubSpot Marketplace approval evidence.

No HubSpot developer project upload, real public app ID, OAuth client ID, production redirect/install URLs, App Marketplace listing, public setup/support evidence, three active unique production installs, reviewer test account, listing approval, or HubSpot review evidence has been observed in this repository.

Do not submit or market a public HubSpot App Marketplace listing until the chosen HubSpot app package is built, installable in a reviewer-safe HubSpot account, validated end to end, linked to a listing, and accepted by HubSpot review.

The existing HubSpot deal and ticket action payloads remain tenant-specific governed action work. They should not be described as capabilities of the public HubSpot App Marketplace app until their broader scope set, tenant mapping, review flow, and audit evidence exist.

The enterprise-safe first package should be a public HubSpot OAuth app for one narrow CRM workflow: create or update a HubSpot contact from a governed Threada WorkItem or lead record. That surface aligns with the live hubspot_upsert_contact action proposal payload and avoids starting with broad CRM object, ticketing, timeline, marketing, or automation scopes.

Deal upsert and ticket update can follow after contact upsert is installed, reviewable, scoped, and audited. A HubSpot CRM card, timeline event, workflow extension, or packaged knowledge sync should wait until the corresponding HubSpot extension, scope set, UI behavior, and reviewer journey exist.

Positioning

Threada for HubSpot should let teams create or update CRM records from governed Threada work without bypassing Threada policy, approval, idempotency, and audit controls.

The narrow v1 app should stay focused:

  • Install Threada into a HubSpot account through HubSpot OAuth.
  • Bind the HubSpot account to a Threada tenant, pack, queue, or workspace mapping.
  • Create or update a HubSpot contact only from an approved Threada action proposal.
  • Show clear setup-required, approval-pending, succeeded, and failed states in Threada.
  • Provide public setup/support documentation that explains least-privilege HubSpot scopes, data handling, disconnect, and uninstall behavior.

The v1 app must not claim that HubSpot can execute arbitrary third-party actions through Threada. Direct external execution remains inside Threada’s governed Work, Studio, MCP, A2A, or first-party runtime paths.

Source Of Truth

Do not duplicate request or response schemas in this document. Public WorkItem shape and governed action proposal behavior are documented in Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

The committed scaffold records the intended local package posture. When real HubSpot developer state exists, the HubSpot public app configuration, OAuth settings, selected scopes, install/uninstall behavior, tenant mapping, listing metadata, reviewer setup notes, HubSpot approval result, and any later certification output must become the source of truth for the public listing. The public setup/support URL for the package is https://docs.threada.ai/integrations/hubspot-setup/.

App Surface

Governed Contact Upsert

The first reviewable capability should create or update a HubSpot contact from a Threada WorkItem or lead record. The implementation should use HubSpot OAuth for installation and token grant, then let Threada create a governed action proposal that writes a contact only after the configured policy and approval path permits it.

Inputs should map to the live hubspot_upsert_contact payload fields for email, first name, last name, phone, company, title, and approved custom properties. Do not expose arbitrary property writes in the public listing until a tenant can review, allowlist, audit, and safely roll back those fields.

Outputs must give the Threada user a clear success, setup-required, approval-pending, or failed state and preserve the HubSpot record reference when one is returned. Do not return only a generic success message; reviewers need to see the install-to-action-to-record journey.

Setup And Tenant Mapping

The app must bind an installed HubSpot account to a Threada tenant, pack, queue, or workspace mapping before claiming production readiness. If setup is incomplete, Threada should show a clear setup-required response instead of silently dropping the request or attempting an unauthenticated HubSpot write.

Reviewer setup notes must include the exact HubSpot test account, HubSpot user, Threada tenant, test pack or queue, install URL, expected contact fields, and cleanup instructions. Credentials, tokens, cookies, raw CRM exports, and customer data must stay out of repo evidence and screenshots.

Deal, Ticket, And CRM UI Follow-Ons

Threada already exposes governed payload types for HubSpot deal upsert and ticket update. A Marketplace listing can reference those capabilities only after the public HubSpot app proves the required scopes, tenant mapping, field allowlists, reviewer flow, and audit behavior for those objects.

HubSpot CRM cards, timeline events, workflow actions, webhook subscriptions, and knowledge sync are out of scope for v1 unless the corresponding HubSpot extension or API surface is built, least-privilege scoped, tested, and reviewed.

Marketplace Package Requirements

HubSpot’s developer platform requires an app configuration with distribution: "marketplace" and auth.type: "oauth" for Marketplace eligibility. HubSpot’s OAuth docs describe the authorization-code install flow used by public apps, and HubSpot’s scopes reference defines the permissions that an app can request. HubSpot Marketplace listing requirements include a single public app ID and OAuth client ID associated with the listing, OAuth as the sole authorization method, at least three active unique production installs, only required scopes, public setup documentation, live support/privacy/terms URLs, accurate shared data and pricing disclosures, and at least one support contact method. HubSpot Certified App status is a later, separate certification path that requires a listed app age and active-install threshold beyond initial listing readiness.

Required package work before submission:

  • HubSpot public app configuration with OAuth client ID, client secret, redirect URLs, app logo, app metadata, and selected scopes.
  • Least-privilege scope set for the v1 surface. For contact-only v1, start with crm.objects.contacts.read and crm.objects.contacts.write, and avoid deal, ticket, workflow, marketing, timeline, user, settings, and sensitive data scopes unless the public v1 needs them.
  • Deployed server-side OAuth callback, state validation, token exchange, token storage in Secret Manager or approved managed identity storage, HubSpot portal discovery through token introspection, rotation posture, and disconnect/uninstall handling. The shared Threada callback supports the contact-scoped v1 path; production launch still needs provider app configuration, reviewer-safe install testing, and uninstall/disconnect evidence.
  • Tenant/account install mapping, setup-required behavior, governed contact upsert proposal creation, execution, idempotency, audit trail, and failure handling.
  • Public setup documentation that is not behind a paywall or sign-in screen, is specific to the Threada HubSpot integration, and explains install, configuration, use, disconnect, uninstall, and data effects.
  • Public support, privacy, terms, security/data-handling, shared-data, and pricing disclosures that match the selected scopes and actual app behavior.
  • App Marketplace listing copy, logo/screenshots, install/start URL, test instructions, setup notes, reviewer account access, and cleanup instructions.
  • HubSpot project upload, AUP/distribution setup, three active unique production installs, listing checks, reviewer setup, and HubSpot review evidence before public-readiness claims.

Explicit Non-Goals

  • No public HubSpot App Marketplace claim until a first-class public HubSpot app exists and HubSpot review passes.
  • No private app token, API key, or manually provisioned tenant secret as the public Marketplace install path.
  • No unmanaged direct HubSpot writes from the Marketplace app.
  • No broad CRM, ticketing, workflow, marketing, timeline, settings, user, or sensitive-data scopes unless the exact v1 capability requires them and the implementation is validated end to end.
  • No packaged HubSpot knowledge sync claim until an authenticated, tenant-scoped, auditable sync path exists and is reviewed.
  • No customer-data screenshots, raw CRM exports, HubSpot account dumps, OAuth tokens, cookies, or private tenant payloads in Marketplace screenshots or review evidence.
  • No positioning as a generic “AI agent executes any HubSpot action” app. Public copy must stay anchored to governed CRM record work, setup, and review.

Review Gates

Implemented:

  • Public API action types include hubspot_upsert_contact, hubspot_upsert_deal, and hubspot_update_ticket.
  • Public BFF mapping code converts HubSpot contact, deal, and ticket payloads into governed action requests and proposal views.
  • Public API docs and generated OpenAPI are published.
  • A private HubSpot App Marketplace package scaffold exists at packages/hubspot-marketplace-app for an OAuth-installed, contact-only v1 app with crm.objects.contacts.read and crm.objects.contacts.write scopes.
  • The shared Marketplace OAuth callback exchanges HubSpot authorization codes, discovers the authorized portal through token introspection, stores the tenant credential in Secret Manager, and upserts a portal-keyed runtime integration with a hubspot_upsert_contact Marketplace action allowlist.
  • The HubSpot runtime adapter validates api.hubapi.com before reading the stored OAuth token.
  • Public HubSpot setup/support documentation exists at HubSpot setup and support.

Missing:

  • Real HubSpot developer project upload, public app ID, OAuth client ID, redirect URLs, app metadata, logo, and selected scopes in the HubSpot developer account.
  • Production OAuth install smoke evidence, refresh/rotation posture, disconnect, and uninstall handling.
  • Self-service tenant/account mapping, setup-required, approval-pending, success, failure, idempotency, and audit behavior.
  • Contact field allowlist and safe custom-property handling.
  • Three active unique production installs with successful app activity in the trailing 30-day HubSpot window required for Marketplace listing.
  • App Marketplace listing copy, shared-data/pricing disclosures, screenshots, test instructions, setup notes, reviewer access, and cleanup instructions.
  • HubSpot listing/review evidence and approval report.
  • Optional later HubSpot Certified App evidence after the app is listed long enough and meets HubSpot’s certification thresholds.

Blocked:

  • Public HubSpot App Marketplace submission is blocked until the first-class HubSpot public app exists, runtime behavior is implemented and testable, OAuth/scopes are least-privilege, HubSpot listing/review gates pass, and reviewer setup is complete.

Launch Checklist

  1. Choose the v1 HubSpot surface. Recommended first: OAuth-installed governed HubSpot contact upsert from a Threada WorkItem or lead record.
  2. Create the HubSpot public app with OAuth redirect URLs, app metadata, logo, and least-privilege scopes.
  3. Rebuild packages/hubspot-marketplace-app with real public app ID, OAuth client ID, redirect/install URLs, support/privacy/terms/setup URLs, and production API URL.
  4. Upload the HubSpot developer project, sign the AUP, and configure distribution/listing settings through an authenticated HubSpot developer account.
  5. Verify the deployed server-side OAuth state validation, token exchange, HubSpot portal introspection, Secret Manager storage, token rotation posture, disconnect, and uninstall handling.
  6. Implement or verify tenant/account mapping, setup-required behavior, governed contact upsert proposal creation, execution, idempotency, audit trail, and failure handling.
  7. Add a contact field allowlist and safe custom-property mapping.
  8. Use the public setup/support guide and prepare App Marketplace listing copy.
  9. Create sanitized screenshots and demo material for install, setup, proposal, approval, execution, resulting HubSpot contact, and disconnect.
  10. Capture three active unique production installs with successful app activity in HubSpot’s trailing 30-day window.
  11. Prepare HubSpot reviewer credentials, test account, setup notes, and cleanup instructions through HubSpot-approved channels.
  12. Submit through HubSpot App Marketplace listing/review and resolve all review issues before claiming Marketplace readiness.
  13. Treat HubSpot Certified App status as a later badge path after the listed app meets HubSpot’s age, install, review, usability, and quality thresholds.

References