HubSpot Sync

HubSpot is not a special case in Opbox. It is one connector configured over the same connection framework that connects any outside system: a CRM, an accounting ledger, a project board. You bring your own CRM, give Opbox encrypted credentials for it, and wire when and how it syncs. The framework owns the credentials, the lifecycle, the schedule, and the inbound guard; the connector is configuration on top, not a bespoke integration built into the product.

What it does

A HubSpot connection lives as a governed record in the workspace, with its secrets encrypted and its sync driven by the same trigger and webhook primitives every other automation uses.

• A connection you create and govern. Author a connection for HubSpot, give it a name, and store the credentials it needs (an OAuth token or an API key). The credential is encrypted at rest with AES-256-GCM and bound to its own row, so a stored secret cannot be lifted and replayed against another record. It never lands in a plain column, is never written to a log, and is never handed back on a read: a read returns metadata and a masked ****<last4> only. Creating a connection is a Sensitive, admin-tier action, because credentials are regulated-adjacent secrets.

• A connection has a clear lifecycle. A connection moves through a guarded state machine: draft, active, disabled, and an error state when a check fails. You can check a connection’s reachability, enable it, disable it, and delete it. Disabling preserves the connection’s sync cursor, so a paused integration resumes from where it left off rather than re-importing from scratch. Deleting a connection retains the tables its past syncs landed in, so historical synced data and the records that referenced it are not destroyed when the link is removed.

• Sync runs on triggers, not a separate engine. When a HubSpot sync should run is expressed as a trigger: a schedule (a cron-style rule that fires on its own) or an event. You author a trigger, test it before it goes live, enable or disable it, and list everything that is wired up. Scheduled and event-driven sync share one set of rules, one audit trail, and the same permission checks, so an automated run and a hand-started one behave identically.

• One inbound webhook door, guarded. HubSpot can also push to Opbox in near-real time through a single inbound webhook verb. That door is the one place untrusted outside traffic enters, so it is hardened: it carries no session of its own, is rate-limited per IP, verifies the raw request body against an HMAC secret, reserves a replay nonce so a captured request cannot be sent twice, and caps the body size. A request that fails any of those checks is rejected before any handler runs. Opbox can also send outbound webhooks through the egress chokepoint when a workflow needs to notify HubSpot or another system.

• Everything stays inside the front door. Every one of these actions is a kernel verb. The connection record, its credentials, its triggers, and the webhook guard all pass through the one front door, where they are permission-checked, scope-checked, and written to the tamper-evident audit record before anything happens. A connection in one workspace is unreachable from another: a cross-workspace lookup reads back as not-found, so the integration cannot be enumerated across tenants.

How you use it

• Connect HubSpot. Author a connection for HubSpot and store its credentials. The secret is encrypted on the way in and masked on every read, so after you save it you never see the raw value again. Run a check to confirm the connection is reachable before you rely on it.

• Schedule the sync. Create a trigger for the connection: a schedule that fires on a cadence you choose, or an event rule. Test the trigger first to see that it resolves the way you expect, then enable it. List your triggers to see everything that is wired up and disable any you want to pause.

• Take HubSpot’s webhooks. Point HubSpot at the inbound webhook door so it can push changes as they happen. The door verifies every request’s signature and rejects anything that fails, so only genuine, unreplayed traffic gets through.

• Pause or disconnect. Disable a connection to stop it syncing while keeping its cursor, so it can resume cleanly later. When you are done with it entirely, delete it: the credentials go, future sync stops, and the data its past runs landed is retained rather than swept away.

The kernel verbs behind it

Each goes through the one front door: permission-checked, scope-checked, and audited before it runs. HubSpot itself adds no verbs of its own (per the bring-your-own-CRM design): it is configured over the generic connection, trigger, and webhook verbs.

• connection.create - author a Connection row for HubSpot, with its credentials encrypted at rest (INV-7).
• connection.check - test that a connection is reachable before you depend on it.
• connection.get - read a connection’s metadata; any stored credential comes back masked, never in the clear.
• connection.list - see every connection configured in the workspace.
• connection.enable - bring a connection into the active state.
• connection.disable - pause a connection, preserving its sync cursor.
• connection.delete - remove a connection while retaining the tables its syncs populated.
• trigger.upsert - author the schedule or event rule that drives a sync.
• trigger.test - check a trigger resolves as expected before it goes live.
• trigger.enable / trigger.disable - turn a sync rule on or off.
• trigger.get / trigger.list - read one trigger or list everything wired up.
• webhook.ingest - the one inbound-webhook guard: no session, IP rate-limited, raw-body HMAC, replay nonce, size cap.
• webhook.send - send an outbound webhook through the egress chokepoint.

See the full set in the connection verb reference, the trigger verb reference, and the webhook verb reference.