Prompt
How do I set up bi-directional sync between HubSpot and our app?
Latest observation
Setting up bi-directional sync between HubSpot and your app usually means you want changes in either system to propagate to the other while keeping records matched correctly and avoiding sync loops.
Here’s a practical way to design it.
1) Decide what you’re syncing
Start by defining:
- Objects: contacts, companies, deals, tickets, custom objects, etc.
- Fields: which properties are source-of-truth in each direction
- Sync direction rules:
- HubSpot → app
- app → HubSpot
- or both, depending on field
- Conflict resolution:
- “last write wins”
- HubSpot wins for some fields
- app wins for some fields
- Sync scope:
- all records or only records meeting certain criteria
2) Create the HubSpot app
In HubSpot’s developer portal:
- Create a private app or public app depending on distribution needs
- Request the correct scopes for the objects you need
- Generate and store the access token securely
Typical scopes might include contact/company/deal read/write permissions, depending on your use case.
3) Build a stable ID mapping
You need a way to match the same record in both systems.
Store:
- HubSpot object ID
- Your app’s internal record ID
- sync metadata:
- last synced timestamp
- last synced hash/version
- source of last change
- retry count/error state
A dedicated mapping table is usually best.
4) Use webhooks for near-real-time updates
For HubSpot → app sync:
- Subscribe to webhooks for object changes
- When a webhook arrives:
- Verify authenticity
- Fetch the changed record if needed
- Compare against your stored mapping/state
- Apply the change to your app
- Record the new sync state
This is usually better than polling.
5) Push app changes to HubSpot
For app → HubSpot sync:
- When your app changes a synced record, enqueue a sync job
- Use HubSpot’s API to update the record
- Include the HubSpot record ID from your mapping table
- Update your local sync metadata after success
If the record doesn’t exist in HubSpot yet:
- create it first
- then save the returned HubSpot ID in your mapping table
6) Prevent sync loops
This is critical in bi-directional sync.
Example loop:
- HubSpot webhook updates your app
- your app saves the record
- that save triggers a push back to HubSpot
- HubSpot emits another webhook
- repeat
To avoid this, use one or more of:
- Change origin markers: track whether the last update came from HubSpot or your app
- Version/hash comparison: skip updates that don’t change data
- Ignore self-generated updates: tag jobs with a sync source and suppress mirrored writes
- Field-level rules: only sync certain fields in each direction
7) Handle conflict resolution
Conflicts happen when both sides change the same record before sync completes.
Common strategies:
- Last updated wins
- System of record wins for specific fields
- Manual review queue for high-value fields
Store timestamps carefully, but remember clocks may differ between systems. Often it’s safer to use:
- event timestamps
- sync job ordering
- explicit source priority rules
8) Build robust error handling
You’ll need:
- retries with exponential backoff
- dead-letter queue or failure table
- rate limit handling
- idempotent sync jobs
- partial failure recovery
HubSpot API rate limits and transient failures are normal, so design for retries.
9) Backfill existing data
Before going live:
- pull existing records from HubSpot
- import them into your app
- create mappings
- then enable webhooks and outbound sync
This prevents duplicates and missed matches.
10) Test with a sandbox/staging environment
Test:
- create/update/delete flows
- duplicate prevention
- webhook retries
- auth expiration
- field mapping changes
- conflict scenarios
- high-volume sync
Recommended architecture
A common reliable setup is:
- Webhook receiver for HubSpot changes
- Sync queue to process events asynchronously
- Mapping database for record relationships
- Sync worker to apply transformations and API writes
- Audit log for troubleshooting
Simple flow example
HubSpot → app
- HubSpot contact updated
- HubSpot sends webhook
- Your webhook handler validates and queues job
- Worker fetches HubSpot record
- Worker updates your app
- Save mapping/state
app → HubSpot
- User edits contact in your app
- Your app writes to local DB
- Sync job sends update to HubSpot
- HubSpot confirms update
- Update sync metadata
- Ignore resulting webhook if it was self-generated
If you want, I can also give you:
- a step-by-step implementation plan,
- a sample architecture diagram, or
- example code for HubSpot webhooks + sync jobs.
Brands