HubSpot Connector

The HubSpot connector enables the indexing of HubSpot CRM tickets and users using the HubSpot API through a private app in your HubSpot account.

Indexed tickets respect HubSpot’s record-level permissions: a ticket is only searchable in Atolio by users who are permitted to view that ticket in HubSpot.

Create a Private App

The connector authenticates using a private app access token. To create the private app, you must be a super admin in your HubSpot account.

1. In HubSpot, navigate to Settings → Integrations → Private Apps.
2. Click Create a private app.
3. On the Basic Info tab, choose a name for the app, e.g. Atolio.
4. On the Scopes tab, add the following scopes:
   • oauth
   • tickets
   • crm.objects.users.read
   • settings.users.read
5. Click Create app.

All four scopes are required. The connector verifies them on startup and will fail with a “missing scopes” error if any are absent.

After the app is created, collect the two credentials the connector needs:

• The access token, found on the app’s Auth tab.
• The client secret, also found on the app’s Auth tab. This is used to verify the authenticity of webhook events sent by HubSpot.

Configure Webhooks

The connector receives ticket changes in real time via HubSpot webhooks. HubSpot does not allow these subscriptions to be created via the API, so they must be configured manually in the private app.

1. Open your private app and go to the Webhooks tab.

2. Set the Target URL to your Atolio deployment’s callback URL. Your Deployment Engineer will provide this; it has the form:

   https://<your-atolio-connector-host>/connectors/hubspot/<instance>/callback/hubspot
   

3. Create subscriptions for the following event types, applied to Tickets:

   • Creation (ticket.creation)
   • Property change (ticket.propertyChange)
   • Deletion (ticket.deletion)

Note: The target URL registered in HubSpot must exactly match the callback URL configured on the Atolio side. Webhook signatures are computed over the full URL, so any mismatch causes all events to be rejected.

Webhooks cover ticket changes only. Changes to users (and to ticket permissions) are picked up by the periodic sync described below.

Provide Configuration

Provide the following values to your Deployment Engineer for them to configure in Atolio:

Sync Behavior

The connector syncs incrementally: each run fetches only tickets and users modified since the previous run. On first run, all tickets and users are indexed.

Periodic syncs are scheduled with the connector’s cron-spec, e.g. */30 * * * * to sync every 30 minutes. The periodic sync is what picks up user changes and ticket permission changes, since webhooks only deliver ticket content changes.

The connector automatically paces its requests to stay within HubSpot’s search API rate limits.

Content Filtering

Atolio supports the ability to avoid certain content from being indexed at all. You can provide inclusions or exclusions with respect to each resource type:

• Users can be filtered w.r.t. their email addresses.
• Tickets can be filtered w.r.t. their ticket IDs.

An example of an inclusions/exclusions configuration would be as follows:

resources:
    user:
        excluded:
            - external_contractor@example.com # user email
    ticket:
        excluded:
            - "1234567890" # ticket ID

If you need content filtering, provide the inclusions & exclusions similar to the above to your Deployment Engineer.

Limitations

• Only tickets with an owner and a subject are indexed. Tickets without an assigned owner are skipped.
• HubSpot service accounts (integration users) are excluded from user indexing.
• Other CRM objects (contacts, companies, deals) are not currently indexed.