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, the app’s Auth tab shows the two credentials the connector needs: the access token and the client secret (used to verify the authenticity of webhook events sent by HubSpot). Both are listed in Required Configuration Values.

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.

Required Configuration Values

Enter these values in the Atolio Admin console (v4.24 and later), or send them to Atolio Support (your Deployment Engineer).

Provided by Atolio: the webhook Target URL (https://<your-atolio-connector-host>/connectors/hubspot/<instance>/callback/hubspot), used for Configure Webhooks.

Keep secrets secure: Share values marked “Yes” in the Secret column only through a password-manager share (e.g. 1Password) or another secure channel agreed with Atolio Support. Never send them in plain email, chat, or support tickets.

Configuration Example

Add this block to connector-values.yaml. Replace each <PLACEHOLDER> with the matching value from the table above, and remove any line marked “Only if” that doesn’t apply.

connectors:
  hubspot:
    default:
      hubspot:
        connector: hubspot
        instance: default
        source: hubspot
        common:
          enabled: true
          identity-provider: false
          cron-spec: "*/30 * * * *"
        secrets:
          access_token:
            value: "<ACCESS_TOKEN>"
          client_secret:
            value: "<CLIENT_SECRET>"
        configuration:
          base_url: "https://api.hubapi.com"

The cron-spec schedules the periodic sync that picks up user and permission changes. See Sync Behavior.

Reference: Configuration Parameters

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.