Connect HubSpot#

Difficulty: simple (OAuth). Connect a HubSpot portal and sync contacts, companies, deals, and tickets in both directions.

Auth at a glance#

What you'll need#

• A HubSpot login that can install an app into your portal.
• The CRM scopes you want Forge to use (Contacts to start; more on request).

Steps#

1. In Connections, choose HubSpot → Connect.
2. HubSpot shows its consent screen listing the scopes Forge is requesting. Pick the portal and click Connect app.
3. You're returned to Anvil with a connected portal. The access token is stored encrypted and refreshed automatically — you never see or manage it.

What you get#

• Source: new and changed contacts/companies/deals/tickets flow into Stream (CRM Search API, polled on a high-water cursor).
• Destination: Forge Load upserts records into HubSpot keyed on an external id, with snapshot/verify/rollback preserved.
• Real-time (opt-in): turn on HubSpot webhooks and changes arrive the moment they happen instead of on the next poll — same Stream events, same triggers.

Real-time webhooks (optional)#

Polling is the default and needs no extra setup. For real-time capture, add a webhook subscription in your HubSpot app (contact/company/deal/ticket created · property-changed · deleted) pointing at your Forge webhook URL. Forge verifies every delivery with HubSpot's request signature (and a 5-minute replay window), so a forged or replayed POST is rejected. Webhook and poll coexist safely — the same change seen both ways is de-duplicated, never double-fired, and polling stays on as the backstop if a delivery is ever missed. The portal a connection belongs to is captured automatically on Connect, so events route to the right connection with no manual mapping.

Gotchas#

• Upsert key. By default Forge upserts on a unique external-id property. On a free/developer portal that property may not exist, so Contacts can be keyed on email instead — set that on the connection. Companies key on domain; Deals and Tickets have no natural free-tier unique key.
• Token lifetime. HubSpot access tokens are short-lived; Forge refreshes them transparently. If a refresh ever fails (you uninstalled the app, revoked access), Forge surfaces it as a permanent "reconnect required" condition rather than retrying against a dead grant — re-run Connect to fix it.
• Archiving is by internal id. A delete resolves the record's internal HubSpot id, archives by it, and confirms the record is gone — so a rollback never lies about a delete that didn't actually happen.

Note: HubSpot is fully live-verified end to end — connect, upsert, read-back, archive, confirm-gone — over OAuth 2.0.