Skip to main content
Connecting HubSpot gives your reps WhiteWhale data — scores, signals, and Why Now summaries — directly inside the CRM they already work in. No spreadsheets, no manual exports.

​
What the integration does

  • Daily sync — WhiteWhale pulls your company and deal data from HubSpot each day and pushes updated scores, signals, and Why Now summaries back to the mapped fields
  • Real-time updates — when a new account is added or activated in WhiteWhale, it immediately syncs to HubSpot
  • Deal context — mapping your deal pipeline lets WhiteWhale surface different signals based on where each prospect is in your sales cycle

​
How the sync works

  • Daily sync window: 5–9 AM ET. WhiteWhale pulls your company and deal records and pushes updated WhiteWhale fields back to HubSpot.
  • Real-time updates: When a new account is added or activated in WhiteWhale, the CRM is updated immediately.
  • First week: Expect a higher volume of requests during initial calibration as the sync establishes its baseline.
  • Read/write scope: WhiteWhale only reads from the fields you map and only writes to the WhiteWhale-specific fields you create. It will not modify any other HubSpot data.

​
Permissions and scopes

WhiteWhale connects via a verified HubSpot public app and requests the minimum permissions needed to function. Required scopes:
  • crm.objects.companies.read
  • crm.objects.companies.write
  • crm.schemas.companies.read
  • oauth
Optional scopes (unlocked when deal mapping is enabled):
  • crm.schemas.deals.read
  • crm.objects.deals.read
  • crm.objects.owners.read
  • crm.schemas.companies.write
  • sales-email-read

​
How to connect

1

Go to Settings

Click Settings in the left nav, then scroll to the HubSpot section.
Screenshot 2026 06 11 At 6 23 55 PM
2

Go to Settings

Click Settings in the left nav, then scroll to the HubSpot section.
Screenshot 2026 06 11 At 6 23 55 PM
3

Click Set Up

You’ll be prompted to connect your HubSpot account. Follow the authentication steps in the HubSpot portal.\
Screenshot 2026 06 11 At 6 24 46 PM
4

Click Set Up

You’ll be prompted to connect your HubSpot account. Follow the authentication steps in the HubSpot portal.\
Screenshot 2026 06 11 At 6 24 46 PM
5

Choose your setup method

Once authenticated, you’ll have two options:
  • One-click setup (recommended) — WhiteWhale maps the standard fields automatically. Best for most teams.
  • Custom mapping — manually map company and deal fields if you need non-standard field names or a more complex CRM setup.
6

Create the custom fields in HubSpot

For one-click setup, WhiteWhale will show you a list of fields to create in HubSpot with their required field types. Create these fields in HubSpot first, then return and click I’ve created these fields and I’m ready to map.For custom setups, open the below information card called “Fields to Create”.

​
Field reference

​
Company fields

These are the fields WhiteWhale reads from and writes to on your HubSpot company records.Create these fields in HubSpot before running setup. All fields should be grouped under Company Information.
  • Field type: Single-line text
  • Label: WhiteWhale Description
  • Description: A summary of the most recent WhiteWhale signals for the company
  • Default value: Blank
  • Field type: Number
  • Label: WhiteWhale Score
  • Description: A score from 0–100 showing the strength of WhiteWhale signals for this company. Scores above 80 are strong but rare — even a score above 10 likely has valuable information.
  • Default value: Blank
  • Field type: Rich text
  • Label: WhiteWhale Signals
  • Description: The most recent signals WhiteWhale found on the company
  • Default value: Blank
  • Field type: Single checkbox
  • Label: WhiteWhale Originated
  • Description: Records if WhiteWhale originated the account
  • Default value: Blank
  • Field type: Date and time picker
  • Label: WhiteWhale Add Date
  • Description: Records the date the account was originally added to WhiteWhale
  • Default value: Blank
  • Field type: Multiple checkboxes
  • Label: WhiteWhale Signal List
  • Description: List of all WhiteWhale signals that apply to this account
  • Option style: Tag (recommended)
  • Options: Enter one placeholder option — WhiteWhale will override with the correct values automatically

​
Deal fields

Mapping your deal pipeline is optional but unlocks two additional capabilities: signal recommendations that adapt based on deal stage, and the ability to backtest which signals correlate most strongly with closed-won deals.

​
Field reference

​
Company fields

These are the fields WhiteWhale reads from and writes to on your HubSpot company records.Create these fields in HubSpot before running setup. All fields should be grouped under Company Information.
  • Field type: Single-line text
  • Label: WhiteWhale Description
  • Description: A summary of the most recent WhiteWhale signals for the company
  • Default value: Blank
  • Field type: Number
  • Label: WhiteWhale Score
  • Description: A score from 0–100 showing the strength of WhiteWhale signals for this company. Scores above 80 are strong but rare — even a score above 10 likely has valuable information.
  • Default value: Blank
  • Field type: Rich text
  • Label: WhiteWhale Signals
  • Description: The most recent signals WhiteWhale found on the company
  • Default value: Blank
  • Field type: Single checkbox
  • Label: WhiteWhale Originated
  • Description: Records if WhiteWhale originated the account
  • Default value: Blank
  • Field type: Date and time picker
  • Label: WhiteWhale Add Date
  • Description: Records the date the account was originally added to WhiteWhale
  • Default value: Blank
  • Field type: Multiple checkboxes
  • Label: WhiteWhale Signal List
  • Description: List of all WhiteWhale signals that apply to this account
  • Option style: Tag (recommended)
  • Options: Enter one placeholder option — WhiteWhale will override with the correct values automatically

​
Deal fields

Mapping your deal pipeline is optional but unlocks two additional capabilities: signal recommendations that adapt based on deal stage, and the ability to backtest which signals correlate most strongly with closed-won deals.
7

Create the custom fields in HubSpot

For one-click setup, WhiteWhale will show you a list of fields to create in HubSpot with their required field types. Create these fields in HubSpot first, then return and click I’ve created these fields and I’m ready to map.For custom setups, you’ll need to have fields of the same type for the system to be able to publish data.

whitewhale_description

  • Field type: Single-line text
  • Label: WhiteWhale Description
  • Description: A summary of the most recent WhiteWhale signals for the company
  • Default value: Blank

whitewhale_score

  • Field type: Number
  • Label: WhiteWhale Score
  • Description: A score from 0–100 showing the strength of WhiteWhale signals for this company. Scores above 80 are strong but rare — even a score above 10 likely has valuable information.
  • Default value: Blank

whitewhale_link

whitewhale_signals

  • Field type: Rich text
  • Label: WhiteWhale Signals
  • Description: The most recent signals WhiteWhale found on the company
  • Default value: Blank

whitewhale_originated

  • Field type: Single checkbox
  • Label: WhiteWhale Originated
  • Description: Records if WhiteWhale originated the account
  • Default value: Blank

whitewhale_add_date

  • Field type: Date and time picker
  • Label: WhiteWhale Add Date
  • Description: Records the date the account was originally added to WhiteWhale
  • Default value: Blank

whitewhale_signal_list

  • Field type: Multiple checkboxes
  • Label: WhiteWhale Signal List
  • Description: List of all WhiteWhale signals that apply to this account
  • Option style: Tag (recommended)
  • Options: Enter one placeholder option — WhiteWhale will override with the correct values automatically
8
Click Test Connection. WhiteWhale will run its checks and flag any errors. Fix any issues and test again until the connection is confirmed.
Screenshot 2026 06 11 At 6 27 04 PM
9

Test the connection

Click Test Connection. WhiteWhale will run its checks and flag any errors. Fix any issues and test again until the connection is confirmed.
Screenshot 2026 06 11 At 6 27 04 PM
Use one-click setup unless you have a specific reason to customize. It takes a couple of minutes and works for the vast majority of HubSpot instances.

​
Setting up the HubSpot App Card

Once your field mapping is complete, you can add the WhiteWhale app card to your HubSpot records so reps can see signal data directly inside HubSpot without leaving the CRM.
1

Install from the HubSpot App Marketplace

Download the WhiteWhale app directly from the HubSpot App Marketplace:

WhiteWhale on HubSpot Marketplace

Install the WhiteWhale app to your HubSpot instance.
2

Authorize the connection

Once installed, authorize WhiteWhale to connect to your HubSpot account:

Authorize WhiteWhale

Click to complete the OAuth authorization.
3

Add the app card in HubSpot

In HubSpot, go to the Card Library and search for BirdDog Research. Add it to the company record layout so it appears on every account page.Not sure how to add app cards? See HubSpot’s guide to installing and managing app cards.
Once the card is added, reps will see WhiteWhale signal data — scores, signals, and the Why Now summary — directly on the HubSpot company record without needing to open WhiteWhale separately.

​
Field reference

​
Company fields

These are the fields WhiteWhale reads from and writes to on your HubSpot company records. Create these fields in HubSpot before running setup. All fields should be grouped under Company Information.
  • Field type: Single-line text
  • Label: WhiteWhale Description
  • Description: A summary of the most recent WhiteWhale signals for the company
  • Default value: Blank
  • Field type: Number
  • Label: WhiteWhale Score
  • Description: A score from 0–100 showing the strength of WhiteWhale signals for this company. Scores above 80 are strong but rare — even a score above 10 likely has valuable information.
  • Default value: Blank
  • Field type: Rich text
  • Label: WhiteWhale Signals
  • Description: The most recent signals WhiteWhale found on the company
  • Default value: Blank
  • Field type: Single checkbox
  • Label: WhiteWhale Originated
  • Description: Records if WhiteWhale originated the account
  • Default value: Blank
  • Field type: Date and time picker
  • Label: WhiteWhale Add Date
  • Description: Records the date the account was originally added to WhiteWhale
  • Default value: Blank
  • Field type: Multiple checkboxes
  • Label: WhiteWhale Signal List
  • Description: List of all WhiteWhale signals that apply to this account
  • Option style: Tag (recommended)
  • Options: Enter one placeholder option — WhiteWhale will override with the correct values automatically

​
Deal fields

Mapping your deal pipeline is optional but unlocks two additional capabilities: signal recommendations that adapt based on deal stage, and the ability to backtest which signals correlate most strongly with closed-won deals.

​
Need help?

If you run into errors during setup or need help with custom field mapping, contact the WhiteWhale team.

Salesforce

Connect WhiteWhale to Salesforce.

Slack

Get signal alerts delivered to Slack.

Webhooks

Push WhiteWhale data to your own systems via webhook.

API Reference

Access WhiteWhale data programmatically.