Integrations

Troubleshoot sync

A four-step diagnostic when a HubSpot or Stripe record is missing or stale in Pivotal.

View as Markdown

A customer should be in Pivotal but isn’t. Or a field went stale and the customer page still shows last quarter’s MRR. Work through these four checks in order before you escalate to support. Three out of four cases resolve on step one or two.

1. Check the connection status

Open Admin > Integrations > [provider]. The banner at the top of the page reads Connected, Reauthorize, or Disconnected.

If it says Reauthorize, the OAuth token expired or your IT team rotated the user who installed it. Click the button and walk the OAuth flow again. Sync resumes automatically.

If it says Disconnected, the connection was deleted (by you, by an admin, or by the provider revoking the app). Reconnect from scratch. Your field mapping is preserved.

2. Check the last sync timestamp

Below the connection banner, you see two timestamps:

  • Last full sync: when the nightly reconciliation last ran.
  • Last incremental update: when the most recent real-time change landed.

If Last incremental update is more than 30 minutes old during business hours, the webhook channel from the provider is broken (HubSpot dropped the subscription, Stripe’s endpoint signature failed). The nightly sync still picks up changes, but real-time is gone until you reconnect.

If Last full sync is more than 24 hours old, the nightly job failed. Click Run sync now and watch the log.

3. Read the integration log

Click View log on the integration page. The log shows every sync attempt for the last 30 days, with status, duration, and error counts. Filter to Errors only.

Common error types and what they mean:

Error codeWhat brokeFix
oauth_revokedThe OAuth token was revoked at the providerClick Reauthorize
source_deletedThe HubSpot company or Stripe customer was deleted at the sourceConfirm intent; if accidental, restore in the provider
field_mapping_invalidA mapped HubSpot property no longer exists or changed typeOpen Field mapping and remap or drop the field
match_ambiguousTwo source records match one Pivotal customerPick the winning record on the Matches tab
rate_limitedThe provider throttled the syncAuto-retries with backoff; no action needed
permission_deniedThe OAuth user lost permission on a HubSpot list or Stripe objectRestore the user’s permission, or reconnect as a user who has it

Click any log row to see the offending record id, the provider response body, and a Retry this record button.

4. Force a resync for one record

If the integration looks healthy but one specific customer is wrong, open the customer page, click the ⋯ menu in the header, and pick Resync from HubSpot or Resync from Stripe. This pulls that one record fresh and overwrites the Pivotal fields the mapping covers.

For a fleet-wide resync, the Run sync now button on the integration page does the same for every mirrored record.

Gotcha: the record was filtered out

If a HubSpot company isn’t in the list you mirror (see Connect HubSpot), the sync never sees it. Check the list membership in HubSpot before assuming the sync is broken.

Email help@pivotal.app with a screenshot of where you got stuck and the customer or onboarding id from the URL.