Tích hợp API HubSpot cho Công cụ Nội bộ Tùy chỉnh: Hướng dẫn Node + Python (2026)

Tích hợp API HubSpot cho Công cụ Nội bộ Tùy chỉnh: Hướng dẫn Node + Python (2026)

Bạn vẫn đang cố tìm một khóa API HubSpot để thiết lập tích hợp API HubSpot của mình? Hãy dừng lại. HubSpot đã ngừng hỗ trợ khóa API tĩnh vào ngày 30 tháng 11 năm 2022 và SDK Node hiện tại (@hubspot/api-client, hiện ở v14) cũng sẽ không chấp nhận nó nữa. Thông tin xác thực phù hợp cho một công cụ nội bộ đơn tài khoản là token truy cập ứng dụng riêng (private app access token), và hướng dẫn này sẽ xây dựng một quy trình đồng bộ hóa thực tế từ HubSpot sang công cụ nội bộ bằng cả Node và Python, từ lệnh gọi create contact đầu tiên của bạn đến một webhook được xác thực chữ ký.

Câu trả lời nhanh: Tích hợp API HubSpot cho phép một công cụ nội bộ tùy chỉnh đọc và ghi dữ liệu CRM thông qua API REST v3 của HubSpot. Đối với công cụ nội bộ đơn tài khoản, hãy xác thực bằng token truy cập ứng dụng riêng (HubSpot đã ngừng API key vào năm 2022), sau đó đồng bộ hóa các thay đổi theo thời gian thực với webhook thay vì dùng cơ chế polling (thăm dò định kỳ).

Dưới đây là những gì bạn sẽ xây dựng:

• Xác thực bằng token ứng dụng riêng cùng với lệnh gọi create contact đầu tiên trong Node và Python
• Một bộ nhận webhook xác thực X-HubSpot-Signature-v3 trước khi tin tưởng payload
• Quy trình đồng bộ hóa an toàn với lỗi 429, xử lý theo lô 100 bản ghi vào hệ thống vé hỗ trợ hoặc ERP nội bộ

Tích hợp API HubSpot hoạt động như thế nào đối với các công cụ nội bộ tùy chỉnh?

Một tích hợp API HubSpot kết nối một công cụ nội bộ tùy chỉnh (ứng dụng vé hỗ trợ, hệ thống ERP, bảng điều khiển thanh toán, cổng khách hàng) với CRM của HubSpot thông qua API REST v3. Công cụ của bạn đọc và ghi các đối tượng CRM (liên hệ, giao dịch, công ty hoặc đối tượng tùy chỉnh) qua HTTPS bằng token truy cập ứng dụng riêng, và các thay đổi thời gian thực được đẩy ngược lại thông qua webhook.

Hãy coi CRM của HubSpot như một cơ sở dữ liệu mà bạn giao tiếp qua HTTP. Mỗi bản ghi là một đối tượng có loại và ID. hubspot crm api integration mà bạn đang xây dựng thực hiện hai nhiệm vụ: đẩy dữ liệu vào HubSpot (tạo liên hệ khi một vé hỗ trợ được mở) và kéo dữ liệu ra khỏi nó (đọc một giao dịch khi bảng điều khiển nội bộ của bạn hiển thị).

Việc đồng bộ hóa chạy theo một trong hai hướng. Đồng bộ một chiều sao chép các thay đổi từ HubSpot vào công cụ của bạn, hoặc từ công cụ của bạn vào HubSpot. Đồng bộ hai chiều thực hiện cả hai và cần có cơ chế bảo vệ vòng lặp, điều mà chúng ta sẽ đề cập sau. Và thay vì hỏi HubSpot "có gì mới không?" mỗi phút (polling), bạn đăng ký một webhook để HubSpot báo cho bạn ngay lập tức khi một bản ghi thay đổi.

Nếu bạn muốn sở hữu hoàn toàn dữ liệu của mình thay vì tích hợp với một CRM lưu trữ, việc tự lưu trữ một CRM mã nguồn mở là một con đường khác đáng để cân nhắc trước khi cam kết. Nhưng nếu HubSpot đã là nguồn dữ liệu chính của bạn, thì API là cách mọi thứ khác giao tiếp với nó.

Đối với công cụ nội bộ đơn tài khoản, bạn không cần OAuth hoặc danh sách trên chợ ứng dụng. Token ứng dụng riêng và một webhook là toàn bộ quá trình tích hợp.

Xác thực vào năm 2026: Tại sao không còn Khóa API HubSpot nữa

Đối với xác thực API HubSpot trên một công cụ nội bộ đơn tài khoản, hãy sử dụng token truy cập ứng dụng riêng. Đây là token bearer tĩnh mà bạn tạo một lần trong tài khoản HubSpot của mình, được giới hạn quyền truy cập chính xác vào các đối tượng mà công cụ của bạn chạm tới. Không có quy trình làm mới và không có thời hạn hết hiệu lực. OAuth tồn tại dành cho các ứng dụng công khai, đa tài khoản, không dành cho bảng điều khiển mà đội ngũ vận hành của bạn chạy nội bộ.

Token ứng dụng riêng so với Khóa API đã bị loại bỏ

Đây là điểm gây nhầm lẫn khiến một nửa số nhà phát triển gặp phải khi tìm kiếm thông tin này. HubSpot đã ngừng hỗ trợ khóa API vào ngày 30 tháng 11 năm 2022 và hiện tại chúng hoàn toàn không được hỗ trợ. Tính năng tự động hoàn thành vẫn gợi ý "hubspot api key" vì thói quen chưa kịp thay đổi, nhưng thực tế không có khóa nào để lấy cả. Hãy chuyển sang sử dụng hubspot private app: tạo nó trong Cài đặt, cấp các phạm vi (scopes) cần thiết và sao chép token truy cập từ tab Auth. Tổng quan về ứng dụng riêng của HubSpot bao gồm các bước thiết lập.

Hai quy tắc đối với bản thân token. Cấp quyền tối thiểu: nếu công cụ của bạn chỉ đọc giao dịch và ghi liên hệ, hãy yêu cầu crm.objects.contacts.write và crm.objects.deals.read, không hơn không kém. Và giữ token trong biến môi trường hoặc trình quản lý bí mật, gửi trong header Authorization: Bearer, không bao giờ hard-code và không bao giờ gửi đến trình duyệt.

Kết luận rất đơn giản. Đối với công cụ nội bộ, hãy sử dụng token truy cập ứng dụng riêng. Chỉ chuyển sang OAuth nếu sau này nó trở thành một ứng dụng công khai, đa tài khoản mà các công ty khác cài đặt vào cổng thông tin của họ.

Lệnh gọi API HubSpot đầu tiên của bạn: Tạo Liên hệ trong Node và Python

Lệnh gọi kinh điển đầu tiên là create contact, và các SDK chính thức giúp việc này chỉ tốn vài dòng mã. Cài đặt client, khởi tạo nó với token ứng dụng riêng từ môi trường, sau đó tạo một liên hệ và đọc lại một giao dịch. Đây là cùng một mẫu bạn sẽ tái sử dụng cho các công ty, vé hỗ trợ và các lệnh gọi hubspot custom objects api, chỉ khác ở loại đối tượng.

Dưới đây là phiên bản Node với @hubspot/api-client (v14):

// npm i @hubspot/api-client   (v14.x)
import { Client } from "@hubspot/api-client";

// Private app token from a secret manager or env var, never hard-coded
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

// Create a contact
const { id } = await hubspot.crm.contacts.basicApi.create({
  properties: {
    email: "[email protected]",
    firstname: "Ada",
    lastname: "Lovelace",
    lifecyclestage: "lead",
  },
  associations: [],
});
console.log("Created contact", id);

// Read a deal by ID
const deal = await hubspot.crm.deals.basicApi.getById(
  "1234567890",
  ["dealname", "amount", "dealstage"],
);
console.log(deal.properties.dealname, deal.properties.amount);

Và tương tự trong Python với hubspot-api-client (v12):

# pip install hubspot-api-client   (v12.x)
import os
from hubspot import HubSpot
from hubspot.crm.contacts import SimplePublicObjectInputForCreate

# Private app token from the environment, not source control
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Create a contact
contact = client.crm.contacts.basic_api.create(
    simple_public_object_input_for_create=SimplePublicObjectInputForCreate(
        properties={
            "email": "[email protected]",
            "firstname": "Ada",
            "lastname": "Lovelace",
            "lifecyclestage": "lead",
        }
    )
)
print("Created contact", contact.id)

# Read a deal by ID
deal = client.crm.deals.basic_api.get_by_id(
    deal_id="1234567890",
    properties=["dealname", "amount", "dealstage"],
)
print(deal.properties["dealname"], deal.properties["amount"])

Mẹo chuyên nghiệp: hãy kiểm thử trên sandbox dành cho nhà phát triển của HubSpot, không bao giờ thử trực tiếp trên môi trường production trước. Một lệnh gọi tạo bị lỗi định dạng trong production sẽ để lại các bản ghi rác thực sự mà đội ngũ bán hàng của bạn phải dọn dẹp. Token, các scope và mô hình đối tượng hoạt động giống hệt nhau trong sandbox.

Làm thế nào để đồng bộ hóa HubSpot với Công cụ Nội bộ theo thời gian thực?

Sử dụng webhook, không dùng polling. Đăng ký gói đăng ký webhook trong ứng dụng riêng của bạn cho đối tượng và sự kiện bạn quan tâm (ví dụ: deal.propertyChange), trỏ nó đến một endpoint HTTPS mà bạn lưu trữ, và HubSpot sẽ POST một mảng JSON nhỏ cho bạn ngay khi một thay đổi phù hợp xảy ra. Chỉ sử dụng polling khi không tồn tại gói đăng ký nào cho thứ bạn cần theo dõi.

Lợi ích là hiệu quả. Polling hỏi "có gì mới không?" mỗi phút và đốt cháy giới hạn tốc độ (rate limit) của bạn khi làm điều đó; một webhook chỉ báo cho bạn biết ngay khi một giao dịch thay đổi. Sự khác biệt đó rất quan trọng ở quy mô lớn, và webhook hiện đã trở nên phổ biến, không còn xa lạ: Báo cáo Tình trạng API năm 2025 của Postman, một cuộc khảo sát hơn 5.700 nhà phát triển, cho thấy khoảng một nửa số đội nhóm dựa vào chúng.

Đăng ký gói đăng ký dưới tab Webhooks của ứng dụng riêng, đặt URL mục tiêu và chọn các sự kiện. HubSpot gửi một mảng các đối tượng sự kiện, mỗi đối tượng mang subscriptionType, objectId và những gì đã thay đổi. Dưới đây là một đoạn mã nhận trong Node với Express:

import express from "express";

const app = express();
// Capture the raw body: you need the exact bytes to validate the signature next
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot POSTs an array of events to this URL
app.post("/webhooks/hubspot", (req, res) => {
  const events = req.body; // [{ subscriptionType: "deal.propertyChange", objectId: 1234, ... }]
  for (const event of events) {
    console.log("HubSpot event:", event.subscriptionType, event.objectId);
    // Do NOT trust this payload yet. The next section validates it before we act.
  }
  res.sendStatus(200);
});

app.listen(3000, () => console.log("Listening on :3000"));

Đây là lúc phần hướng dẫn thực hành trở nên nghiêm túc. Giả sử bạn đang đồng bộ hóa một giao dịch vào bản ghi ERP của một nhà sản xuất nhỏ: webhook kích hoạt, trình xử lý của bạn tạo hoặc cập nhật vé ERP tương ứng, và đội ngũ vận hành của bạn thấy sự thay đổi mà không cần chạm vào HubSpot. Đó là cùng một cách tiếp cận thời gian thực mà chúng tôi sử dụng để đồng bộ hóa tác nhân giọng nói với CRM, chỉ khác là trigger là thay đổi thuộc tính thay vì cuộc gọi điện thoại. Một cảnh báo: đoạn mã trên tin tưởng bất cứ thứ gì được POST vào nó. Hãy sửa điều đó trước khi đưa vào hoạt động.

Xác thực Chữ ký Webhook (v3) để Không bao giờ tin tưởng Payload giả mạo

Xác thực mọi webhook đến bằng chữ ký v3. HubSpot ký mỗi yêu cầu bằng bí mật ứng dụng (app secret) của bạn và gửi hai header, X-HubSpot-Signature-v3 và X-HubSpot-Request-Timestamp. Từ chối bất cứ thứ gì cũ hơn 5 phút, xây dựng lại chuỗi nguồn dưới dạng method + full URL + raw body + timestamp, mã hóa HMAC-SHA256 nó với bí mật ứng dụng, mã hóa base64 và so sánh trong thời gian không đổi (constant time).

Nếu bạn bỏ qua bước này, bất kỳ ai đoán được URL webhook của bạn đều có thể giả mạo một bản cập nhật giao dịch. Việc xác thực là bắt buộc. Tài liệu xác thực yêu cầu của HubSpot và nhật ký thay đổi chữ ký v3 nêu rõ công thức chính xác. Dưới đây là middleware Express có thể sử dụng ngay:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // from your private app settings
const MAX_AGE_MS = 5 * 60 * 1000; // reject anything older than 5 minutes

export function validateHubSpotSignature(req, res, next) {
  const signature = req.header("X-HubSpot-Signature-v3");
  const timestamp = req.header("X-HubSpot-Request-Timestamp");

  // 1. Reject stale requests (replay protection)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Rebuild the exact source string: method + full URL + raw body + timestamp
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

  // 3. HMAC-SHA256 with the app secret, base64-encoded
  const hash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(source, "utf8")
    .digest("base64");

  // 4. Constant-time compare against the header
  const expected = Buffer.from(hash);
  const received = Buffer.from(signature);
  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(401);
  }
  next();
}

Cùng một kiểm tra dưới dạng hàm Python, để bao phủ cả hai ngăn xếp:

import base64
import hashlib
import hmac
import os
import time

CLIENT_SECRET = os.environ["HUBSPOT_APP_SECRET"].encode("utf-8")
MAX_AGE_MS = 5 * 60 * 1000  # 5 minutes

def is_valid_signature(method, uri, body, signature, timestamp):
    # 1. Reject stale requests
    if not signature or not timestamp:
        return False
    if int(time.time() * 1000) - int(timestamp) > MAX_AGE_MS:
        return False

    # 2. method + full URL + raw body + timestamp
    source = f"{method}{uri}{body}{timestamp}".encode("utf-8")

    # 3. HMAC-SHA256, base64
    digest = hmac.new(CLIENT_SECRET, source, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode("utf-8")

    # 4. Constant-time compare
    return hmac.compare_digest(expected, signature)

Điểm gây rắc rối khiến nhiều người mất cả buổi chiều: HubSpot ký toàn bộ URL mục tiêu, bao gồm scheme, host và path gộp lại. Đằng sau proxy, bộ cân bằng tải hoặc đường hầm ngrok, req.get("host") có thể báo cáo host nội bộ thay vì host công khai mà HubSpot đã ký. Nếu việc xác thực liên tục thất bại trên một payload mà bạn chắc chắn là hợp lệ, hãy ghi log chính xác URI bạn đã xây dựng lại và so sánh nó với URL webhook công khai của bạn, từng ký tự một.

Giới hạn Tốc độ, Lỗi 429 và Batch API: Những gì chúng tôi đã chạy trong Production

Các ứng dụng riêng nhận được khoảng 10 yêu cầu mỗi giây (100 mỗi 10 giây trên gói Free/Starter, 190 mỗi 10 giây trên gói Pro/Enterprise) với giới hạn hàng ngày từ 250.000 đến 1.000.000. Cái bẫy: CRM Search bị giới hạn riêng biệt ở mức 4 yêu cầu mỗi giây, và các endpoint batch chấp nhận tối đa 100 bản ghi mỗi yêu cầu. Hướng dẫn sử dụng của HubSpot liệt kê các tầng này.

Đây là nơi lý thuyết gặp phải bảng điều khiển staging màu đỏ. Trong quá trình điền dữ liệu lại (backfill) vào mùa xuân này, chúng tôi đã đẩy khoảng 8.000 bản ghi hiện có vào HubSpot từ một công cụ vé hỗ trợ nội bộ và làm phong phú mỗi bản ghi bằng một tra cứu CRM Search. Chúng tôi đang chạy @hubspot/api-client v14 ở phía Node và hubspot-api-client v12 cho worker làm phong phú dữ liệu bằng Python. Các thao tác ghi hàng loạt diễn ra suôn sẻ. Các lệnh gọi Search sụp đổ trong vòng một phút, bởi vì worker của chúng tôi đang firing Search ở khoảng 15 req/s so với trần cứng 4 req/s mà chúng tôi chưa tính toán riêng.

Hai thay đổi đã khắc phục điều này. Đầu tiên, một wrapper retry đọc các header phản hồi X-HubSpot-RateLimit-* và giảm tốc độ khi gặp lỗi 429:

// Wrap any HubSpot call; retries on 429 with exponential backoff
async function withRetry(fn, maxRetries = 5) {
  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (err) {
      const status = err.code ?? err.response?.status;
      if (status !== 429 || attempt >= maxRetries) throw err;

      // Honor HubSpot's reset window if the header is present
      const headers = err.response?.headers ?? {};
      const resetMs = Number(headers["x-hubspot-ratelimit-interval-milliseconds"]) || 0;
      const backoff = Math.max(resetMs, 2 ** attempt * 500); // 0.5s, 1s, 2s, 4s...

      console.warn(`429 hit, retry ${attempt + 1} in ${backoff}ms`);
      await new Promise((r) => setTimeout(r, backoff));
      attempt++;
    }
  }
}

Thứ hai, chúng tôi ngừng ghi các bản ghi từng cái một. Endpoint batch chấp nhận tối đa 100 bản ghi mỗi POST /crm/v3/objects/{objectType}/batch/create, vì vậy chúng tôi chia nhỏ quá trình backfill thành 80 lệnh gọi batch thay vì 8.000 lệnh POST đơn lẻ:

// HubSpot batch endpoints accept at most 100 records per request
function chunk(arr, size = 100) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

// POST /crm/v3/objects/contacts/batch/create, chunked to 100 at a time
async function batchCreateContacts(records) {
  for (const group of chunk(records, 100)) {
    const inputs = group.map((r) => ({
      properties: { email: r.email, firstname: r.firstName, lastname: r.lastName },
      associations: [],
    }));
    await withRetry(() => hubspot.crm.contacts.batchApi.create({ inputs }));
    console.log(`Wrote ${group.length} contacts`);
  }
}

Việc giới hạn worker Search ở 4 req/s và batch hóa các lệnh ghi đã biến một quy trình vốn đang chìm trong các lần retry thành một quy trình hoàn thành âm thầm. Nếu bạn nhớ một con số từ phần này, hãy nhớ số 4: giới hạn CRM Search là rào cản gây khó khăn trong production, và đó là điều mà mọi bài tổng hợp thường quên nhắc đến. Nhân tiện, giới hạn batch "10 cho liên hệ" cũ đã biến mất; hiện tại là 100 trên tất cả các loại đối tượng.

Đi theo hướng Hai chiều: Ghi thay đổi ngược lại HubSpot mà không tạo Vòng lặp Vô hạn

Đồng bộ hai chiều ghi các thay đổi ngược lại HubSpot từ công cụ nội bộ của bạn cũng như đọc chúng vào. Nguy hiểm nằm ở vòng lặp phản hồi: lệnh ghi ngược của bạn kích hoạt chính webhook đã kích hoạt trình xử lý của bạn, dẫn đến việc ghi lại, mãi mãi. Ngăn chặn điều này bằng khóa idempotency (bỏ qua các thay đổi bạn đã áp dụng) và cờ nguồn (bỏ qua các sự kiện đến do chính công cụ của bạn gây ra).

const processed = new Set(); // use Redis or a unique DB constraint in production

async function writeBackToHubSpot(record) {
  // Dedup key: object id + a hash of the change we're about to apply
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // already synced this exact change
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Tag the source so the resulting webhook is ignored by our own receiver
      // (check for source: "internal-tool" before acting on an inbound event)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Mẫu này rất nhỏ, nhưng bỏ qua nó là cách một quy trình đồng bộ âm thầm tăng gấp đôi khối lượng ghi của bạn qua đêm. Khi dữ liệu sạch ở cả hai chiều, các đội nhóm thường chuyển tiếp nó xuống dòng vào quy trình AI SDR hoặc lớp báo cáo. Hướng dẫn tích hợp HubSpot của Nango là một tài liệu tham khảo solid chỉ dùng Node nếu bạn muốn một góc nhìn khác về đồng bộ hai chiều, mặc dù bạn sẽ cần tự port ý tưởng ngăn vòng lặp.

Bạn nên Tự xây dựng hay Thuê đối tác Tích hợp?

Tự xây dựng nội bộ khi quy trình đồng bộ hóa nhỏ, ổn định và thuộc quyền sở hữu: luồng một chiều, một vài đối tượng và một kỹ sư có thể hấp thụ các thay đổi phá vỡ (breaking changes) khoảng hai lần một năm của HubSpot. Thuê đối tác khi bạn cần đồng bộ hai chiều, mô hình hóa đối tượng tùy chỉnh, hoặc khi không ai trong đội nhóm có thể đảm nhận việc bảo trì liên tục. Yếu tố quyết định hiếm khi là việc xây dựng ban đầu; mà là ai sẽ giám sát nó một năm sau đó.

Dưới đây là danh sách kiểm tra trung thực. Tự xây dựng nếu: hướng đi là một chiều, bạn đang đồng bộ hóa các đối tượng tiêu chuẩn, bạn có một nhà phát triển có thể lưu trữ endpoint webhook, và ai đó sẽ nhận thấy khi một payload bắt đầu thất bại. Mọi thứ ở trên là bản thiết kế của bạn.

Thuê đối tác nếu: bạn cần đồng bộ hai chiều với ngăn ngừa vòng lặp trên nhiều đối tượng, bạn đang mô hình hóa các đối tượng tùy chỉnh với các liên kết typed, bạn đang kết nối nhiều hệ thống (HubSpot cộng với ERP cộng với thanh toán), hoặc người sẽ bảo trì nó đã quá tải. HubSpot sử dụng phiên bản API dựa trên ngày với các thay đổi phá vỡ chỉ khoảng hai lần một năm, nghe có vẻ nhẹ nhàng cho đến khi một thay đổi xảy ra trong tuần bận rộn nhất của bạn và không có người chịu trách nhiệm. Đuôi bảo trì đó, chứ không phải lần deploy đầu tiên, mới là thứ âm thầm đánh sập các tích hợp nội bộ. Nếu bạn không muốn sở hữu nó, đó là lúc dịch vụ tích hợp CRM tùy chỉnh của chúng tôi phát huy tác dụng.

Những điểm chính

• Không còn khóa API HubSpot nữa. Sử dụng token truy cập ứng dụng riêng cho công cụ nội bộ đơn tài khoản; OAuth chỉ dành cho các ứng dụng công khai, đa tài khoản.
• Luôn xác thực X-HubSpot-Signature-v3 trước khi tin tưởng payload webhook. Xây dựng lại chuỗi nguồn với URL mục tiêu đầy đủ.
• Tôn trọng giới hạn 4 req/s của CRM Search và batch hóa các lệnh ghi lớn thành các khối 100 với cơ chế giảm tốc khi gặp lỗi 429.
• Ưu tiên webhook hơn polling cho đồng bộ hóa thời gian thực, và tích hợp HubSpot là một phần của hệ sinh thái công cụ AI cho doanh nghiệp rộng lớn hơn.

Bị mắc kẹt ở khía cạnh bảo trì, hoặc muốn có thêm một cặp mắt xem xét trước khi bạn phát hành? Đặt lịch tư vấn tích hợp miễn phí. Không áp lực dù theo cách nào; mã nguồn ở trên là của bạn để chạy bất kể.

Về Tác giả

Mert Batur Gurbuz là Đồng sáng lập của Techsy.io, nơi đội ngũ phát triển các tác nhân AI, hệ thống tự động hóa và quy trình voice/SDR cho khách hàng B2B. Anh ấy đang học tại Đại học Birmingham và viết về ngăn xếp công cụ LLM mà đội ngũ Techsy thực sự sử dụng trong production. Thông tin xác thực: Đồng sáng lập, Techsy.io, Đại học Birmingham. Kết nối trên LinkedIn.

Câu hỏi Thường gặp

Tôi vẫn cần khóa API HubSpot vào năm 2026 phải không?

Không. HubSpot đã ngừng hỗ trợ khóa API tĩnh vào ngày 30 tháng 11 năm 2022 và chúng hoàn toàn không được hỗ trợ. Tính năng tự động hoàn thành vẫn gợi ý "hubspot api key" do thói quen, nhưng không có gì để lấy cả. Đối với công cụ nội bộ đơn tài khoản, hãy tạo một ứng dụng riêng trong Cài đặt và sử dụng token truy cập của nó thay thế.

Sự khác biệt giữa token ứng dụng riêng và OAuth cho HubSpot là gì?

Token truy cập ứng dụng riêng là thông tin xác thực tĩnh cho một tài khoản HubSpot duy nhất, không có thời hạn hết hiệu lực và không có quy trình làm mới, lý tưởng cho công cụ nội bộ. OAuth 2.0 dành cho các ứng dụng công khai, đa tài khoản mà các công ty khác cài đặt vào cổng thông tin của họ; token của nó hết hạn sau khoảng sáu giờ và yêu cầu chu kỳ làm mới.

Giới hạn tốc độ API của HubSpot vào năm 2026 là gì?

Các ứng dụng riêng nhận được khoảng 10 yêu cầu mỗi giây (100 mỗi 10 giây trên gói Free/Starter, 190 trên gói Pro/Enterprise) với giới hạn hàng ngày từ 250.000 đến 1.000.000. API CRM Search bị giới hạn riêng biệt ở mức 4 yêu cầu mỗi giây, và các endpoint batch chấp nhận tối đa 100 bản ghi mỗi yêu cầu.

Làm thế nào để xác thực chữ ký webhook của HubSpot?

Sử dụng công thức v3: từ chối các yêu cầu có X-HubSpot-Request-Timestamp cũ hơn năm phút, sau đó xây dựng chuỗi nguồn gồm method cộng với URL mục tiêu đầy đủ cộng với raw body cộng với timestamp. Mã hóa HMAC-SHA256 nó với bí mật ứng dụng của bạn, mã hóa base64 kết quả và so sánh nó với X-HubSpot-Signature-v3 trong thời gian không đổi.

Tôi nên sử dụng SDK HubSpot nào, Node hay Python?

Cả hai đều chính thức và được duy trì. Node sử dụng @hubspot/api-client (v14) và Python sử dụng hubspot-api-client (v12). Chúng cung cấp cùng một mô hình đối tượng CRM v3, vì vậy hãy chọn cái phù hợp với ngăn xếp của bạn. Hướng dẫn này cung cấp mã xác thực và xác thực chữ ký giống hệt nhau bằng cả hai ngôn ngữ.

Làm thế nào để đồng bộ hóa HubSpot với công cụ nội bộ tùy chỉnh theo thời gian thực?

Đăng ký gói đăng ký webhook trong ứng dụng riêng của bạn cho đối tượng và sự kiện bạn quan tâm, sau đó lưu trữ một endpoint HTTPS mà HubSpot sẽ POST đến khi một thay đổi phù hợp xảy ra. Xác thực chữ ký, sau đó ghi thay đổi vào công cụ nội bộ của bạn. Chỉ sử dụng polling khi không có gói đăng ký webhook nào bao phủ những gì bạn cần.

Service Key của HubSpot là gì và tôi có nên sử dụng nó không?

Service Key là thông tin xác thực chỉ dành cho dữ liệu, cấp độ tài khoản mà HubSpot đưa vào beta công khai vào tháng 2 năm 2026. Nó nhắm đến các tác vụ phía máy chủ chỉ chạm vào dữ liệu. Đối với công cụ nội bộ tiêu chuẩn hiện nay, token truy cập ứng dụng riêng vẫn là mặc định an toàn hơn, được ghi chép tốt hơn; hãy coi Service Keys là beta cho đến khi chúng chính thức ra mắt.

Tôi có thể kiểm thử tích hợp HubSpot mà không ảnh hưởng đến production không?

Có. Tạo sandbox nhà phát triển HubSpot và trỏ token ứng dụng riêng của bạn vào đó. Các scope, mô hình đối tượng, webhook và giới hạn tốc độ hoạt động giống như production, vì vậy bạn có thể tạo các liên hệ thử nghiệm và kích hoạt webhook mà không để lại các bản ghi rác cho đội ngũ bán hàng của bạn phải dọn dẹp sau này.

Batch API của HubSpot có thể nhận bao nhiêu bản ghi cùng lúc?

Các endpoint batch (POST /crm/v3/objects/{objectType}/batch/create và các anh em update và upsert của nó) chấp nhận tối đa 100 bản ghi mỗi yêu cầu. Chia các payload lớn hơn thành các nhóm 100. Giới hạn "10 bản ghi cho liên hệ" cũ mà một số hướng dẫn vẫn trích dẫn đã bị xóa; 100 là mức hiện tại trên tất cả các loại đối tượng.

Tôi nên tự xây dựng điều này nội bộ hay thuê một agency?

Tự xây dựng nội bộ khi quy trình đồng bộ hóa là một chiều, sử dụng các đối tượng tiêu chuẩn và có người chịu trách nhiệm có thể hấp thụ các thay đổi phá vỡ hai lần một năm của HubSpot. Thuê đối tác cho đồng bộ hai chiều, mô hình hóa đối tượng tùy chỉnh, hoặc khi không ai có thể đảm nhận việc bảo trì. Lần deploy đầu tiên rất dễ dàng; một năm bảo trì sau đó mới là chi phí thực sự.