HubSpot technical integration guide

This guide describes what Revial does inside your HubSpot account, so you can approve, configure and later audit the integration. For connecting see Connecting Revial to HubSpot; for every property read and written, and each app's scopes, see What Revial syncs with HubSpot.

1. What you are approvingCopy Anchor Link

Revial uses two separate HubSpot apps, each with its own client ID, token and scopes:

2. What your admin has to doCopy Anchor Link

Webhook subscriptions for the Calls app are configured once in Revial's HubSpot app; there is nothing to set up in your account.

3. Authentication and token modelCopy Anchor Link

Both apps use the same endpoints:

State. A random state, valid for five minutes and bound to the Revial user; the callback re-checks the user's admin role. The Calls app consumes its state before continuing, so each state can be used only once.

Storage. Access and refresh tokens are encrypted at rest (AES-256-GCM) and never sent to the browser.

Refresh failures. A 401 or invalid_grant is permanent. For the CRM app the connection is marked as needing re-authorisation and an organisation admin is notified; the hourly sync skips it. For the Calls app, queued calls for that connection are dropped until it is reconnected.

Who may connect on the Revial side. An organisation owner or admin on a plan with the CRM integration; rate-limited. One CRM app connection and one Calls app connection per organisation. A portal can be connected to only one organisation's Calls app.

4. The installing userCopy Anchor Link

Everything happens as the installing user. Records that user cannot see do not reach Revial, and notes and deals Revial creates are created by that user's token. Which HubSpot roles may install apps is set in your HubSpot account.

5. Sync cadence and API consumption (CRM app)Copy Anchor Link

• Cadence: roughly every hour, starting immediately after connecting.
• First sync: list API, 100 records per page, up to 50,000 per object type.
• Later syncs: search API filtered by last-modified date, 100 per page (HubSpot caps search results at 10,000 per query).
• Activities: up to 3,000 per sync; a larger backlog continues on later syncs from where it stopped.
• Associations: batch reads of 100 for activities; one request per changed deal.
• Deletions: only deleted (archived) deals are detected and removed.
• Rate limiting: about 3 requests per second per worker. 429 responses wait for Retry-After (2 seconds if absent) and 5xx responses back off exponentially, up to 3 retries; requests time out after 30 seconds.
• Per run: 5 pages per job run, continuing automatically.

6. The call-analysis pipeline (Calls app)Copy Anchor Link

1. Webhook — HubSpot notifies Revial when a call is created or its recording link changes. Revial verifies the X-HubSpot-Signature-v3 HMAC with the app secret and rejects requests older than five minutes. Events for unknown portals are ignored.
2. Queue — each call is queued; a lock per portal and call ID ensures it is processed once.
3. Owner check — calls with no owner, or an unmapped or excluded owner, are skipped.
4. Recording — Revial fetches the recording (up to 500 MB, 10-minute timeout, HTTPS only; the token is sent only to HubSpot hosts) or, where the recording is not fetchable, HubSpot's own transcript. Which source works is remembered per portal.
5. Storage and transcription — recordings are stored in Revial's EU storage and deleted after 365 days. Where an organisation has recordings deleted as soon as the transcript exists, the audio is removed at that point instead. Audio is transcribed by Revial's transcription provider, which deletes its copy after processing.
6. Meeting — a Revial meeting is created for the mapped user and analysed.

If a recording is not attached yet, the call is retried a few times and then dropped without creating a meeting. Such a call leaves no trace in Revial — if a call you expected to be analysed never appears, contact support.

7. Field mappings (CRM app)Copy Anchor Link

Admins map Revial summary fields and custom extraction fields to properties on contacts, companies, deals and meetings under Organization → CRM Settings → Property Mapping. Properties are listed with the crm.schemas.*.read scopes. Conversion and overwrite rules are on the data page, section 9.3.

8. Meeting-to-CRM matchingCopy Anchor Link

First match wins: direct IDs on the meeting; the open deal it is already linked to; attendee emails → contacts → their deals (scored); company by website or email domain; company by name. Scoring favours open deals, the attendee being the primary contact, other attendees on the deal, title similarity, later stages and recency. Closed deals are excluded; free-email domains are ignored for company matching.

9. Security, limits and failure behaviourCopy Anchor Link

• Separate apps: call analysis can be granted without CRM write access, and vice versa.
• Secrets: tokens encrypted at rest; only connection status is exposed to the browser.
• Webhook integrity: signature v3 with a five-minute replay window.
• Recording download safety: redirect and private-address checks on every hop.
• Data storage: synced records and raw API responses are stored in Revial and deleted when the CRM app is disconnected.

10. Auditing and disconnectingCopy Anchor Link

In HubSpot: Connected apps in your account settings lists both Revial apps and lets you uninstall them; records Revial creates show the installing user.

Disconnecting the CRM app in Revial deletes Revial's synced copy, tokens and field mappings. It does not revoke the token — uninstall the app in HubSpot to end the grant.

Disconnecting the Calls app in Revial revokes the refresh token in HubSpot, removes owner mappings and ignores further webhooks from the portal. Meetings already created, and stored recordings until their 365-day expiry, remain.

11. TroubleshootingCopy Anchor Link