Oppy for HubSpot

Overview

Oppy connects to your HubSpot portal to enrich strategy cards with live CRM context and push approved cards into HubSpot — creating or updating Contacts and Companies, linking them together, and attaching a context Note.

Writes are one-way (Oppy → HubSpot). Separately, HubSpot deal and contact events feed back into Oppy as card outcome badges (won, lost, stalled) to improve future recommendations — Oppy never overwrites your HubSpot records from those events.

Prerequisites

Before installing, you need:

• An active Oppy account.
• Admin permissions in Oppy (the Integrations settings are admin-only).
• Admin access to the target HubSpot portal to authorize the app.
• No other CRM connected. Oppy supports one CRM at a time — if Attio is connected, disconnect it first (Oppy shows: "Disconnect Attio first — one CRM at a time.").

Installation & Setup

1. In the Oppy dashboard, open Integrations (sidebar → Account & Billing).
2. Find HubSpot and click Connect with HubSpot.
3. You are redirected to HubSpot to approve access, then returned to Oppy automatically.
4. The HubSpot card shows a Connected badge and your portal ID.
5. (Optional) Enable Auto-sync on approval to enrich the contact and push it to HubSpot automatically when you approve a card. Leave it off to push manually only.
6. Review Sync health on the Integrations page — pending pushes, failed pushes in the last 24 hours, and the last error message. If failures appear, click Retry failed pushes to re-queue them.

Open a card on Approvals to load lifecycle stage, owner, and deal context from HubSpot.

Permissions (OAuth scopes)

During authorization, Oppy requests these HubSpot scopes:

• Contacts — Read and write
• Companies — Read and write
• Deals — Read
• Owners — Read
• Contact schemas — Write (creates Oppy custom contact properties on connect)

Notes are created via the Contacts write scope. HubSpot does not require separate notes or tasks scopes in the authorization flow.

CRM context on cards

When a contact is revealed on a card, Oppy fetches fresh HubSpot context and displays it on the card:

• Lifecycle stage
• Contact owner
• Last activity date
• Open deal count and first open deal stage

If the contact is not found in HubSpot, Oppy shows "Not found in HubSpot".

If the contact already has a different owner in HubSpot, Oppy shows a warning: "Contact already owned by {name} in HubSpot. Pushing will not overwrite the owner." Pushing still updates contact fields and creates a note, but the existing HubSpot owner is preserved.

How It Works — Data Mapping

Direction: Oppy → HubSpot for record writes. HubSpot → Oppy is read-only for CRM context on cards, plus outcome badges from deal/contact lifecycle events.

When a card is pushed, Oppy writes up to four records:

Contact — HubSpot contacts (upsert by email)

Field	Source / rule
email	match key
firstname	if present
lastname	if present
jobtitle	if present
hs_linkedin_url	if present
phone / mobilephone	if present (both set to the same number)
hubspot_owner_id	acting SDR on create only
oppy_signal_type	Oppy custom property
oppy_card_tier	Oppy custom property
oppy_trigger_summary	Oppy custom property
oppy_last_push_date	Oppy custom property (date of last push)
oppy_card_url	Oppy custom property (deep link to card)

note

Oppy creates the custom contact properties in an Oppy property group in your HubSpot portal automatically when you connect.

Company — HubSpot companies (upsert by domain)

Field	Source / rule
domain	match key
name	company name
numberofemployees	if present

Association

• Contact → Company (linked on every push when a company domain is available)

Note (associated with Contact)

• Body: signal trigger summary + card strategy text + deep link back to the card in Oppy

Re-push behavior

• Contact — matched by email and updated in place (no duplicate).
• Company — matched by domain and updated in place (no duplicate).
• Owner — set from the acting SDR on create only; never overwritten on update.
• Note — a new note is created on every push, so notes accumulate.

Triggers — When Oppy Syncs

• Sync in HubSpot — manual button on an individual card row on Approvals.
• View in HubSpot — opens the contact record in HubSpot after a successful sync.
• Sync all in HubSpot — bulk button that pushes all eligible cards (in batches of 50).
• Auto-sync on approval (optional) — enriches the contact and pushes to HubSpot automatically when a card is approved.

If HubSpot rate-limits a push, Oppy queues it and retries automatically. The UI shows "Queued — will retry" until the push succeeds.

Deal outcomes (feedback loop)

When deals move stage or contacts change lifecycle in HubSpot, Oppy updates matching strategy cards with outcome badges (won, lost, stalled). This feeds Oppy's adaptive learning loop so future recommendations improve over time.

No extra setup is required — Oppy registers the necessary webhooks when you connect HubSpot.

Support & Troubleshooting

• Questions or issues: contact@oppyone.com
• If a push is rate-limited, Oppy shows "HubSpot rate limit — try again in a moment." — simply retry shortly after, or wait for the automatic retry queue.
• Check Sync health on the Integrations page for pending or failed pushes.
• You can disconnect any time via Disconnect HubSpot in Integrations. Cards stop showing CRM context and pushing to HubSpot until you reconnect.
• If your HubSpot admin revokes access, reconnect via Connect with HubSpot.