Before connecting HubSpot to a partner marketplace

A successful OAuth screen proves that an account granted permissions. It does not prove that the marketplace knows which records may move, which system owns each field, how conflicts resolve, when a sync must stop, or how operators recover after partial failure. Those decisions belong in a readiness review before installation.

Partner Connector exposes integration, stage-mapping, sync-history, and conflict-management workflows in its authenticated client. This checklist describes how to prepare for those workflows without claiming that every portal, app version, or scope set is identical. Verify the exact current manifest and authorization screen in a controlled HubSpot account at go-live.

1. Define the business flow

Write the permitted flow in plain language before mapping objects:

• Which HubSpot records can become marketplace candidates?
• Which qualification and non-fit states make a record eligible?
• Which fields enter a masked preview versus an accepted packet?
• What marketplace events write back to HubSpot?
• Which reply, objection, suppression, ownership, or deal event stops transfer?

“Sync contacts” is not a business flow. Use explicit verbs such as read eligible contacts, create a listing preview, reserve ownership, unlock an accepted packet, write a marketplace status, and close the loop with an outcome.

2. Map systems and identities

Document every identity boundary: HubSpot portal, installing user, Partner Connector organization, partner, seller, buyer, application, and webhook source. Decide how a portal maps to one marketplace tenant and how administrators detect a duplicate or wrong-portal connection.

The account that installs the app is not automatically the permanent data owner. Record who can reconnect, revoke, change mappings, view diagnostics, and approve new permissions. Use server-side token storage and never place OAuth access or refresh tokens in browser storage, logs, resource pages, or support screenshots.

3. Review scopes against actions

Build a permission matrix from the current app manifest and HubSpot authorization screen:

Do not copy a scope list from an old document. HubSpot requires scopes to match the APIs used, and app requirements can change. Treat any newly requested scope as a product and security change with partner re-consent implications.

4. Define field ownership

For every mapped field, assign one rule:

• HubSpot-owned: the marketplace can read but not overwrite it.
• Marketplace-owned: Partner Connector writes the canonical marketplace state.
• Derived: computed from named inputs, with a version and recomputation rule.
• Manual: a human resolves changes; automatic sync must not win silently.

Include null handling, enumeration mapping, timestamp semantics, deletion behavior, and unsupported values. A stage labelled “Closed lost” in one portal may not mean eligible for transfer in another.

5. Design conflict states before normal states

List likely conflicts and the safe default:

• both systems changed the same field;
• the record was merged, deleted, or reassigned;
• a won or active opportunity appears after listing;
• the person opted out or objected in one system only;
• the seller edits a lead after a buyer reserved it;
• an event arrives twice or out of order;
• credentials expire during a batch.

Prefer quarantine and operator review over silent last-write-wins behavior for ownership, eligibility, privacy, or money-related conflicts. The partner-ready record should retain provenance so a reviewer can understand what changed.

6. Validate incoming requests and events

OAuth state must bind the callback to the initiating session and tenant. Webhook requests require current signature verification using the raw request body and the correct app secret. Processors need idempotency based on a stable event identifier, safe retries with backoff, and logs that omit credentials and unnecessary personal data.

A successful HTTP response should mean the event was safely accepted, not necessarily that every downstream write completed. Track queued, processed, failed, retried, and dead-letter states separately.

7. Test in a controlled account

1. Create representative records without real prospect data.
2. Verify the authorization screen shows only expected scopes.
3. Map normal, null, unsupported, and custom values.
4. Run an initial sync and record object counts by permitted category.
5. Repeat the same event to prove idempotency.
6. Send events out of order and create a concurrent edit.
7. Revoke credentials and confirm the system stops safely.
8. Reconnect, reconcile, and prove no duplicate listing or ownership change occurred.
9. Capture permission-safe screenshots of mappings, diagnostics, conflicts, and recovery.

8. Define the operational dashboard

Operators need connection identity, token health without token exposure, last successful sync, next scheduled work, records evaluated, eligible, skipped, conflicted, and failed, plus the reason and owner for unresolved states. Trend counts should link to records or redacted diagnostics rather than becoming unexplained health scores.

Keep integration health separate from marketplace performance. A technically healthy sync can still transfer the wrong records if eligibility or ownership rules are weak.

Go-live decision

Approve installation only when the team can explain the flow, current scopes, field owners, stop events, conflict defaults, test evidence, monitoring, revocation, and recovery. Name the person authorized to make that decision and record the manifest version reviewed.

After launch, changes to scopes, mappings, eligibility, ownership, or suppression handling reopen the review. OAuth consent is not permanent approval for a materially different workflow.

Sources and next step

Use HubSpot’s official documentation for OAuth, scopes, and webhooks as the technical source of truth. Confirm current requirements against the app type actually deployed.

Then define how marketplace events become measurable outcomes with the attribution ladder.