How to Integrate Replit with HubSpot

HubSpot Private Apps replaced legacy API keys as the recommended authentication method. To create one, log into HubSpot, click the settings gear icon in the top navigation bar, then go to Integrations > Private Apps in the left sidebar. Click 'Create a private app', give it a name like 'Replit CRM Integration', and navigate to the Scopes tab. For contact management, enable crm.objects.contacts.read and crm.objects.contacts.write. For deal access, add crm.objects.deals.read. You can add more scopes later, but start with the minimum required — this limits blast radius if the token is ever compromised. Click 'Create app', then on the confirmation dialog click 'Continue creating'. HubSpot will display your token starting with 'pat-'. Copy this token immediately — it is only shown once in full. If you lose it, you'll need to rotate it from the Private Apps dashboard. Never paste this token directly into your code files — Replit's Secret Scanner will flag it, and it would end up in version control.

Open your Repl in the Replit editor. Look for the lock icon (🔒) in the left sidebar — clicking it opens the Secrets pane. Click 'New Secret', enter HUBSPOT_TOKEN as the key, and paste your Private App token as the value. Click 'Add Secret'. The value is now AES-256 encrypted and will be injected as an environment variable when your app runs. Replit Secrets are scoped to the individual Repl — they are never included when someone forks your project, only the key name is visible to others. If you have multiple Repls that need the same token, you can use account-level secrets to share credentials across projects without duplicating them. After adding the secret, you do not need to restart the editor — it takes effect on the next run. For production deployments, secrets sync automatically when you deploy.

1# Python — verify secret is loaded
2import os
3
4hubspot_token = os.environ.get("HUBSPOT_TOKEN")
5if not hubspot_token:
6    raise EnvironmentError("HUBSPOT_TOKEN secret is not set. Add it in Replit Secrets (lock icon).")
7print("HubSpot token loaded successfully")

HubSpot provides an official Python SDK (hubspot-api-client) and a Node.js SDK (@hubspot/api-client), but you can also call the REST API directly using requests (Python) or node-fetch (Node.js). For full control and lighter dependencies, the direct HTTP approach is recommended for Replit projects. In Node.js, install Express with npm install express. In Python, Flask and requests are available by default but install them explicitly via the Packages pane or requirements.txt. The HubSpot API base URL is https://api.hubapi.com. All requests require the Authorization: Bearer YOUR_TOKEN header. The CRM objects API v3 endpoint pattern is /crm/v3/objects/{objectType} where objectType is contacts, deals, companies, or other CRM objects. Always use HTTPS and include a Content-Type: application/json header for POST and PATCH requests. Connection timeouts should be set explicitly — HubSpot's API can occasionally be slow during peak times.

1// Node.js — HubSpot API helper (hubspot.js)
2const HUBSPOT_TOKEN = process.env.HUBSPOT_TOKEN;
3if (!HUBSPOT_TOKEN) throw new Error('HUBSPOT_TOKEN secret not set');
4
5const BASE_URL = 'https://api.hubapi.com';
6
7async function hubspotRequest(method, path, body = null) {
8  const options = {
9    method,
10    headers: {
11      'Authorization': `Bearer ${HUBSPOT_TOKEN}`,
12      'Content-Type': 'application/json'
13    }
14  };
15  if (body) options.body = JSON.stringify(body);
16
17  const response = await fetch(`${BASE_URL}${path}`, options);
18  if (!response.ok) {
19    const error = await response.json();
20    throw new Error(`HubSpot API error ${response.status}: ${JSON.stringify(error)}`);
21  }
22  return response.json();
23}
24
25module.exports = { hubspotRequest };

With the API helper in place, you can now create contacts, read them by ID, and search for contacts by email or any property. The CRM API v3 uses a consistent pattern: POST to /crm/v3/objects/contacts to create, GET /crm/v3/objects/contacts/{id} to read, PATCH /crm/v3/objects/contacts/{id} to update, and POST /crm/v3/objects/contacts/search to find contacts by property values. When creating a contact, properties are nested under a 'properties' key in the request body. HubSpot contact properties include standard fields like email, firstname, lastname, phone, and company, as well as any custom properties you define in your HubSpot portal. For upsert behavior (create or update based on email), use POST /crm/v3/objects/contacts with the idProperty=email query parameter — HubSpot will match on email and update if found or create if not. The search endpoint accepts filter groups for complex queries and supports pagination with limit and after parameters.

1// Node.js — Create and search contacts (server.js)
2const express = require('express');
3const { hubspotRequest } = require('./hubspot');
4const app = express();
5app.use(express.json());
6
7// Create a new contact
8app.post('/contacts', async (req, res) => {
9  try {
10    const { email, firstname, lastname, company } = req.body;
11    const contact = await hubspotRequest('POST', '/crm/v3/objects/contacts', {
12      properties: { email, firstname, lastname, company }
13    });
14    res.json({ id: contact.id, properties: contact.properties });
15  } catch (err) {
16    res.status(500).json({ error: err.message });
17  }
18});
19
20// Search contacts by email
21app.get('/contacts/search', async (req, res) => {
22  try {
23    const { email } = req.query;
24    const result = await hubspotRequest('POST', '/crm/v3/objects/contacts/search', {
25      filterGroups: [{
26        filters: [{ propertyName: 'email', operator: 'EQ', value: email }]
27      }],
28      properties: ['email', 'firstname', 'lastname', 'company', 'hs_lead_status']
29    });
30    res.json(result.results);
31  } catch (err) {
32    res.status(500).json({ error: err.message });
33  }
34});
35
36app.listen(3000, '0.0.0.0', () => console.log('Server running on port 3000'));

HubSpot can push real-time notifications to your Replit app when CRM events occur — contacts are created, deals change stage, properties are updated, and more. To set this up, you first need a stable deployed URL from Replit. Deploy your app by clicking the Deploy button in the editor and choosing Autoscale deployment. Your app will receive a permanent URL like https://your-app-name.your-username.replit.app. In HubSpot, go to Settings > Integrations > Private Apps, select your app, and click the Webhooks tab. Enter your Replit deployment URL plus the webhook path (e.g., https://your-app.replit.app/webhook) as the Target URL. Add a subscription for the event types you want — for example, contact.creation or deal.propertyChange. HubSpot sends webhook payloads as POST requests with a JSON array of events. Each event includes the objectId, subscriptionType, portalId, changeSource, and eventId fields. You should verify the webhook authenticity by checking the X-HubSpot-Signature header against an HMAC-SHA256 hash of the raw body using your app's client secret.

1// Node.js — HubSpot webhook receiver
2const crypto = require('crypto');
3
4const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
5
6function verifyHubSpotSignature(rawBody, signature) {
7  if (!HUBSPOT_CLIENT_SECRET) return true; // Skip in dev if not set
8  const hash = crypto
9    .createHmac('sha256', HUBSPOT_CLIENT_SECRET)
10    .update(rawBody)
11    .digest('hex');
12  return hash === signature;
13}
14
15app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
16  const signature = req.headers['x-hubspot-signature'];
17  if (!verifyHubSpotSignature(req.body, signature)) {
18    return res.status(401).json({ error: 'Invalid signature' });
19  }
20
21  const events = JSON.parse(req.body);
22  events.forEach(event => {
23    console.log(`Event: ${event.subscriptionType}, Object ID: ${event.objectId}`);
24    // Handle each event type
25    if (event.subscriptionType === 'contact.creation') {
26      console.log(`New contact created: ${event.objectId}`);
27    }
28  });
29
30  res.json({ received: true });
31});

If you prefer Python, the pattern is identical but uses the requests library and Flask. Install requests and flask via the Packages pane or add them to requirements.txt. The same environment variable pattern applies — os.environ['HUBSPOT_TOKEN'] retrieves the secret you stored in Replit Secrets. Flask's request object gives you access to POST body data via request.get_json() and query parameters via request.args. For production Python deployments on Replit, Flask works well with Autoscale since it handles concurrent requests via Gunicorn. The HubSpot Python SDK (hubspot-api-client) is also available — install it with pip and it provides typed methods for every CRM operation. However, the direct requests approach has fewer dependencies and is easier to debug when API calls fail, since you can inspect raw request and response objects.

1# Python — Flask HubSpot CRM integration (app.py)
2import os
3import requests
4from flask import Flask, request, jsonify
5
6app = Flask(__name__)
7
8HUBSPOT_TOKEN = os.environ["HUBSPOT_TOKEN"]
9BASE_URL = "https://api.hubapi.com"
10HEADERS = {
11    "Authorization": f"Bearer {HUBSPOT_TOKEN}",
12    "Content-Type": "application/json"
13}
14
15@app.route("/contacts", methods=["POST"])
16def create_contact():
17    data = request.get_json()
18    payload = {
19        "properties": {
20            "email": data.get("email"),
21            "firstname": data.get("firstname"),
22            "lastname": data.get("lastname"),
23            "company": data.get("company")
24        }
25    }
26    resp = requests.post(f"{BASE_URL}/crm/v3/objects/contacts",
27                         json=payload, headers=HEADERS, timeout=10)
28    resp.raise_for_status()
29    contact = resp.json()
30    return jsonify({"id": contact["id"], "email": contact["properties"]["email"]})
31
32@app.route("/contacts/<contact_id>", methods=["GET"])
33def get_contact(contact_id):
34    resp = requests.get(
35        f"{BASE_URL}/crm/v3/objects/contacts/{contact_id}",
36        params={"properties": "email,firstname,lastname,company"},
37        headers=HEADERS, timeout=10
38    )
39    resp.raise_for_status()
40    return jsonify(resp.json()["properties"])
41
42if __name__ == "__main__":
43    app.run(host="0.0.0.0", port=3000)