Skip to main content

HubSpot

HubSpot is a leading customer relationship management (CRM) platform that helps businesses manage their sales, marketing, customer service, and operations. With HubSpot, organizations can track customer interactions, manage deals through sales pipelines, create support tickets, and automate marketing campaigns all in one place.

Authentication Types​

HubSpot supports 1 authentication method:

  • OAuth - Create your own HubSpot app and connect each user with their HubSpot account.
    • Pros: Secure, per-user tracking, production-ready, supports all HubSpot features, granular permission control
    • Cons: Requires HubSpot admin access to create the app
    • Best for: Organizations wanting full control, compliance requirements, and production deployments

Setting up OAuth​

To use HubSpot with Webrix, you need to create a HubSpot app and configure OAuth authentication.

1. Create an MCP Auth App​

  1. Log in to your HubSpot account

  2. Click Development in the sidebar

  3. Click MCP Auth Apps (Beta)

  4. Click Create MCP Auth App

  5. Give it a name (e.g., "Webrix Integration")

  6. Copy the Redirect URI from Webrix and paste it

    tip

    You can find the Redirect URI in Webrix when configuring the HubSpot connector under the OAuth settings.

  7. Click Create

  8. Copy the Client ID and Client Secret from the app details

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select HubSpot and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID in the Client ID field

  5. Paste your Client Secret in the Client Secret field

  6. Click Save Changes

4. Test the Connection​

  1. After saving, click Connect to test the OAuth flow

  2. You'll be redirected to HubSpot to authorize the app

  3. Select your HubSpot account and click Connect app

  4. You'll be redirected back to Webrix with a successful connection

IMPORTANT: Users installing this connector must be a HubSpot Super Admin or have App Marketplace Access permissions in their HubSpot account.

Troubleshooting​

Redirect URI Mismatch Error​

If you see "redirect_uri_mismatch" error during OAuth authorization.

Cause: The redirect URL configured in your HubSpot app doesn't match the one being used during the OAuth flow.

Solution:

  1. Copy the exact Redirect URL from Webrix
  2. Go to your HubSpot app → Auth tab → Redirect URLs
  3. Ensure the URL is added exactly as shown (including https:// and any trailing slashes)
  4. Save the changes and try connecting again

Token Refresh Failures​

If users are repeatedly prompted to reconnect or get "invalid token" errors.

Cause: The refresh token may have been revoked, or there's an issue with token storage.

Solution:

  1. Disconnect and reconnect the HubSpot integration in Webrix
  2. Verify that the app hasn't been uninstalled or had its credentials changed in HubSpot
  3. Check that your HubSpot app's OAuth settings haven't been modified

"Access Denied" Error​

Users see "access_denied" when trying to authorize the app.

Cause: The user doesn't have sufficient permissions in HubSpot, or they clicked "Cancel" during authorization.

Solution:

  1. Ensure the user has Super Admin or App Marketplace Access permissions in HubSpot
  2. Try the authorization flow again
  3. If the issue persists, verify that the HubSpot account is active and in good standing

Rate Limiting​

API requests fail with 429 (Too Many Requests) errors.

Cause: HubSpot enforces API rate limits to ensure platform stability. The limits vary by subscription tier.

Solution:

  1. HubSpot typically allows 100-150 requests per 10 seconds for most APIs
  2. Implement retry logic with exponential backoff in your workflows
  3. Consider upgrading your HubSpot subscription for higher rate limits
  4. Batch operations where possible (e.g., using search APIs instead of multiple get requests)

Missing or Incorrect Object IDs​

Errors when trying to associate objects or update records.

Cause: Using the wrong object ID or trying to associate objects that don't exist.

Solution:

  1. HubSpot object type IDs: Contacts (0-1), Companies (0-2), Deals (0-3), Tickets (0-5)
  2. Use the search or list tools to find the correct object IDs before associating or updating
  3. Verify that the object exists in your HubSpot account
  4. When using associations, ensure both objects exist and you have permission to access them