Ενσωμάτωση HubSpot API για Προσαρμοσμένα Εσωτερικά Εργαλεία: Οδηγός Node + Python (2026)

Ενσωμάτωση HubSpot API για Προσαρμοσμένα Εσωτερικά Εργαλεία: Οδηγός Node + Python (2026)

Ακόμα ψάχνετε για κλειδί HubSpot API για να συνδέσετε την ενσωμάτωσή σας στο HubSpot API; Σταματήστε να ψάχνετε. Το HubSpot κατάργησε τα στατικά κλειδιά API στις 30 Νοεμβρίου 2022 και το τρέχον Node SDK (@hubspot/api-client, πλέον στην έκδοση v14) δεν θα δεχτεί ένα τέτοιο κλειδί ούτως ή άλλως. Το σωστό διαπιστευτήριο για ένα εσωτερικό εργαλείο ενός λογαριασμού είναι ένα token πρόσβασης ιδιωτικής εφαρμογής (private app access token), και αυτός ο οδηγός κατασκευάζει έναν πραγματικό συγχρονισμό HubSpot-προς-εσωτερικό-εργαλείο τόσο σε Node όσο και σε Python, από την πρώτη σας κλήση create contact έως ένα webhook με επικύρωση υπογραφής.

Σύντομη απάντηση: Μια ενσωμάτωση HubSpot API επιτρέπει σε ένα προσαρμοσμένο εσωτερικό εργαλείο να διαβάζει και να γράφει δεδομένα CRM μέσω του v3 REST API του HubSpot. Για ένα εσωτερικό εργαλείο ενός λογαριασμού, πραγματοποιήστε πιστοποίηση με ένα token πρόσβασης ιδιωτικής εφαρμογής (το HubSpot απέσυρε τα κλειδιά API το 2022) και στη συνέχεια συγχρονίστε τις αλλαγές σε πραγματικό χρόνο με webhooks αντί για polling.

Αυτό θα κατασκευάσετε:

• Πιστοποίηση με token ιδιωτικής εφαρμογής plus την πρώτη σας κλήση create contact σε Node και Python
• Έναν receiver webhook που επικυρώνει το X-HubSpot-Signature-v3 πριν εμπιστευτεί ένα payload
• Έναν συγχρονισμό ασφαλής ως προς το σφάλμα 429, με batch των 100 εγγραφών, προς μια εσωτερική εγγραφή ticketing ή ERP

Πώς Λειτουργεί η Ενσωμάτωση HubSpot API για Προσαρμοσμένα Εσωτερικά Εργαλεία;

Μια ενσωμάτωση HubSpot API συνδέει ένα προσαρμοσμένο εσωτερικό εργαλείο (μια εφαρμογή ticketing, ένα ERP, έναν πίνακα ελέγχου τιμολόγησης, μια πύλη πελατών) με το CRM του HubSpot μέσω του v3 REST API. Το εργαλείο σας διαβάζει και γράφει αντικείμενα CRM (επαφές, συμφωνίες, εταιρείες ή προσαρμοσμένα αντικείμενα) μέσω HTTPS με ένα token πρόσβασης ιδιωτικής εφαρμογής, και οι αλλαγές σε πραγματικό χρόνο ρέουν πίσω μέσω webhooks.

Σκεφτείτε το CRM του HubSpot ως μια βάση δεδομένων με την οποία συνομιλείτε μέσω HTTP. Κάθε εγγραφή είναι ένα αντικείμενο με έναν τύπο και ένα ID. Η hubspot crm api integration που κατασκευάζετε κάνει δύο δουλειές: pushes δεδομένα μέσα στο HubSpot (δημιουργία επαφής όταν ανοίγει ένα ticket) και τραβάει δεδομένα έξω από αυτό (ανάγνωση μιας συμφωνίας όταν αποδίδεται ο εσωτερικός σας πίνακας ελέγχου).

Ο συγχρονισμός εκτελείται προς μία από δύο κατευθύνσεις. Ένας one-way sync αντιγράφει αλλαγές από το HubSpot στο εργαλείο σας, ή από το εργαλείο σας στο HubSpot. Ένας two-way sync κάνει και τα δύο και χρειάζεται προστασία από βρόχους (loop protection), την οποία θα καλύψουμε αργότερα. Και αντί να ρωτάτε το HubSpot "υπάρχει κάτι νέο;" κάθε λεπτό (polling), καταχωρείτε ένα webhook ώστε το HubSpot να σας ενημερώνει τη στιγμή που αλλάζει μια εγγραφή.

Αν προτιμάτε να κατέχετε εξ ολοκλήρου τα δεδομένα σας αντί να ενσωματώσετε ένα hosted CRM καθόλου, η self-hosting ενός open-source CRM είναι μια διαφορετική διαδρομή που αξίζει να σταθμίσετε πριν δεσμευτείτε. Αλλά αν το HubSpot είναι ήδη η πηγή της αλήθειας σας, το API είναι ο τρόπος με τον οποίο όλα τα άλλα επικοινωνούν με αυτό.

Για ένα εσωτερικό εργαλείο ενός λογαριασμού, δεν χρειάζεστε OAuth ή listing στην marketplace εφαρμογών. Ένα token ιδιωτικής εφαρμογής και ένα webhook αποτελούν ολόκληρη την ενσωμάτωση.

Πιστοποίηση το 2026: Γιατί Δεν Υπάρχει Πια Κλειδί HubSpot API

Για την πιστοποίηση HubSpot API σε ένα εσωτερικό εργαλείο ενός λογαριασμού, χρησιμοποιήστε ένα token πρόσβασης ιδιωτικής εφαρμογής. Είναι ένα στατικό bearer token που δημιουργείτε μία φορά στον λογαριασμό σας στο HubSpot, περιορισμένο ακριβώς στα αντικείμενα που αγγίζει το εργαλείο σας. Δεν υπάρχει ροή refresh και δεν υπάρχει λήξη. Το OAuth υπάρχει για δημόσιες, πολυλογαριασμικές εφαρμογές, όχι για τον πίνακα ελέγχου που η ομάδα operations σας εκτελεί εσωτερικά.

Token Ιδιωτικής Εφαρμογής vs Το Καταργημένο Κλειδί API

Εδώ βρίσκεται η παγίδα που παραπλανεί τους μισούς developers που φτάνουν σε αυτό το SERP. Το HubSpot απέσυρε τα κλειδιά API στις 30 Νοεμβρίου 2022, και πλέον δεν υποστηρίζονται καθόλου. Η autoComplete λειτουργία συνεχίζει να προτείνει "hubspot api key" επειδή η μυϊκή μνήμη δεν έχει προλάβει, αλλά δεν υπάρχει κλειδί για ανάκτηση. Προτιμήστε μια hubspot private app: δημιουργήστε την στις Ρυθμίσεις, χορηγήστε τα scopes που χρειάζεται και αντιγράψτε το token πρόσβασης από την καρτέλα Auth. Η επισκόπηση ιδιωτικών εφαρμογών του HubSpot καλύπτει τη ρύθμιση.

Δύο κανόνες για το ίδιο το token. Χορηγήστε ελάχιστη προνομιακή πρόσβαση (least privilege): αν το εργαλείο σας διαβάζει μόνο συμφωνίες και γράφει επαφές, ζητήστε crm.objects.contacts.write και crm.objects.deals.read, τίποτα περισσότερο. Και κρατήστε το token σε μια environment variable ή σε έναν secret manager, στέλνοντάς το στην κεφαλίδα Authorization: Bearer, ποτέ hard-coded και ποτέ shipped στον browser.

Η ετυμηγορία είναι απλή. Για ένα εσωτερικό εργαλείο, χρησιμοποιήστε ένα token πρόσβασης ιδιωτικής εφαρμογής. Καταφύγετε στο OAuth μόνο αν αυτό αργότερα γίνει μια δημόσια, πολυλογαριασμική εφαρμογή που άλλες εταιρείες εγκαθιστούν στα δικά τους portals.

Η Πρώτη σας Κλήση HubSpot API: Δημιουργία Επαφής σε Node και Python

Η κανονική πρώτη κλήση είναι create contact, και τα επίσημα SDKs την κάνουν με λίγες γραμμές. Εγκαταστήστε τον client, αρχικοποιήστε τον με το token της ιδιωτικής σας εφαρμογής από το environment, στη συνέχεια δημιουργήστε μια επαφή και διαβάστε μια συμφωνία πίσω. Αυτό είναι το ίδιο μοτίβο που θα επαναχρησιμοποιήσετε για εταιρείες, tickets και κλήσεις hubspot custom objects api, μόνο ο τύπος του αντικειμένου αλλάζει.

Εδώ είναι η έκδοση Node με @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);

Και το ίδιο πράγμα σε Python με 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"])

Pro tip: δοκιμάστε σε ένα developer sandbox του HubSpot, ποτέ πρώτα σε production. Μια malformed create κλήση σε production αφήνει πραγματικές junk εγγραφές που η ομάδα πωλήσεων σας πρέπει να καθαρίσει. Το token, τα scopes και το μοντέλο αντικειμένων συμπεριφέρονται identically στο sandbox.

Πώς Συγχρονίζετε το HubSpot με ένα Εσωτερικό Εργαλείο σε Πραγματικό Χρόνο;

Χρησιμοποιήστε webhooks, όχι polling. Καταχωρήστε μια subscription webhook στην ιδιωτική σας εφαρμογή για το αντικείμενο και το event που σας ενδιαφέρει (π.χ., deal.propertyChange), δείξτε την σε ένα HTTPS endpoint που φιλοξενείτε, και το HubSpot σας POSTάρει έναν μικρό JSON array τη στιγμή που συμβαίνει μια αντίστοιχη αλλαγή. Κάντε polling μόνο όταν δεν υπάρχει subscription για αυτό που πρέπει να παρακολουθήσετε.

Το όφελος είναι η αποδοτικότητα. Το polling ρωτά "υπάρχει κάτι νέο;" κάθε λεπτό και καίει το rate limit σας κάνοντάς το· ένα webhook απλώς σας λέει τη στιγμή που αλλάζει μια συμφωνία. Αυτή η διαφορά έχει σημασία σε κλίμακα, και τα webhooks είναι πλέον mainstream, όχι εξωτικά: η Έκθεση State of the API 2025 της Postman, μια έρευνα σε περισσότερους από 5.700 developers, διαπίστωσε ότι περίπου οι μισές ομάδες βασίζονται σε αυτά.

Καταχωρήστε την subscription στην καρτέλα Webhooks της ιδιωτικής σας εφαρμογής, ορίστε το target URL και επιλέξτε τα events. Το HubSpot στέλνει έναν array από event objects, το καθένα μεταφέροντας το subscriptionType, το objectId και τι άλλαξε. Εδώ είναι ένα stub receiver σε Node με 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"));

Εδώ είναι που η διαδικασία κατασκευής γίνεται πραγματική. Ας πούμε ότι συγχρονίζετε μια συμφωνία σε μια εγγραφή ERP μιας μικρής κατασκευαστικής εταιρείας: το webhook πυροδοτείται, ο handler σας δημιουργεί ή ενημερώνει το αντίστοιχο ticket ERP, και η ομάδα ops σας βλέπει την αλλαγή χωρίς να αγγίξει το HubSpot. Είναι η ίδια προσέγγιση πραγματικού χρόνου που χρησιμοποιούμε για να συγχρονίσουμε έναν voice agent με ένα CRM, μόνο που το trigger είναι μια αλλαγή ιδιότητας αντί για τηλεφωνική κλήση. Μια προειδοποίηση: το παραπάνω stub εμπιστεύεται οτιδήποτε POSTάρεται σε αυτό. Διορθώστε το πριν πάτε live.

Επικύρωση Υπογραφών Webhook (v3) Για Να Μην Εμπιστευτείτε Ποτέ Ένα Forged Payload

Επικυρώστε κάθε εισερχόμενο webhook με την υπογραφή v3. Το HubSpot υπογράφει κάθε αίτημα με το app secret σας και στέλνει δύο κεφαλίδες, X-HubSpot-Signature-v3 και X-HubSpot-Request-Timestamp. Απορρίψτε οτιδήποτε παλαιότερο από 5 λεπτά, ανακατασκευάστε το source string ως method + full URL + raw body + timestamp, εφαρμόστε HMAC-SHA256 με το app secret, encode σε base64 και συγκρίνετε σε constant time.

Αν το παραλείψετε, οποιοσδήποτε μαντέψει το webhook URL σας μπορεί να πλαστογραφήσει μια ενημέρωση συμφωνίας. Η επικύρωση δεν είναι προαιρετική. Το doc επικύρωσης αιτημάτων του HubSpot και το changelog υπογραφών v3 περιγράφουν την ακριβή συνταγή. Εδώ είναι ως drop-in middleware Express:

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();
}

Ο ίδιος έλεγχος ως συνάρτηση Python, ώστε να καλύπτονται και τα δύο stacks:

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)

Η παγίδα που κοστίζει στους ανθρώπους ένα απόγευμα: Το HubSpot υπογράφει το full target URL, scheme και host και path μαζί. Πίσω από ένα proxy, έναν load balancer ή ένα tunnel ngrok, το req.get("host") μπορεί να αναφέρει το internal host αντί για το public one που υπέγραψε το HubSpot. Αν η επικύρωση αποτυγχάνει συνεχώς σε ένα payload που είστε σίγουροι ότι είναι legit, καταγράψτε το ακριβές URI που ανακατασκευάσατε και συγκρίνετέ το με το public webhook URL σας, χαρακτήρα προς χαρακτήρα.

Rate Limits, 429s και Batch API: Τι Εκτελέσαμε σε Production

Οι ιδιωτικές εφαρμογές λαμβάνουν περίπου 10 αιτήματα ανά δευτερόλεπτο (100 ανά 10 δευτερόλεπτα σε Free/Starter, 190 ανά 10 δευτερόλεπτα σε Pro/Enterprise) με ένα ημερήσιο cap μεταξύ 250.000 και 1.000.000. Η παγίδα: Το CRM Search έχει ξεχωριστό cap στα 4 αιτήματα ανά δευτερόλεπτο, και τα batch endpoints δέχονται μέγιστο 100 εγγραφές ανά αίτημα. Οι οδηγίες χρήσης του HubSpot παραθέτουν τα tiers.

Εδώ είναι που η θεωρία συνάντησε έναν κόκκινο staging πίνακα ελέγχου. Κατά διάρκεια ενός backfill αυτή την άνοιξη, pushάραμε περίπου 8.000 υπάρχουσες εγγραφές στο HubSpot από ένα εσωτερικό εργαλείο ticketing και enrichάραμε καθεμία με ένα lookup CRM Search. Τρέχαμε @hubspot/api-client v14 στην πλευρά Node και hubspot-api-client v12 για έναν Python enrichment worker. Τα bulk writes ήταν εντάξει. Οι κλήσεις Search κατέρρευσαν μέσα σε ένα λεπτό, επειδή ο worker μας έστελνε Search στα περίπου 15 req/s ενάντια σε ένα hard ceiling 4 req/s που δεν είχαμε υπολογίσει ξεχωριστά.

Δύο αλλαγές το διόρθωσαν. Πρώτον, ένας retry wrapper που διαβάζει τις κεφαλίδες απόκρισης X-HubSpot-RateLimit-* και κάνει backoff σε ένα 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++;
    }
  }
}

Δεύτερον, σταματήσαμε να γράφουμε εγγραφές μία προς μία. Το batch endpoint δέχεται έως 100 εγγραφές ανά POST /crm/v3/objects/{objectType}/batch/create, έτσι χωρίσαμε το backfill σε 80 batch κλήσεις αντί για 8.000 single POSTs:

// 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`);
  }
}

Ο περιορισμός του Search worker στα 4 req/s και το batching των writes μετέτρεψαν μια εκτέλεση που πνιγόταν σε retries σε μία που ολοκληρώθηκε ήσυχα. Αν θυμάστε έναν αριθμό από αυτή την ενότητα, ας είναι το 4: το cap του CRM Search είναι το όριο που χτυπά σε production, και είναι αυτό που κάθε roundup post ξεχνά να αναφέρει. Παρεμπιπτόντως, το παλιό batch ceiling "10 για επαφές" έχει φύγει· το τρέχον είναι 100 across object types.

Going Two-Way: Γράφοντας Αλλαγές Πίσω στο HubSpot Χωρίς Άπειρους Βρόχους

Ένας two-way sync γράφει αλλαγές πίσω στο HubSpot από το εσωτερικό σας εργαλείο καθώς και τις διαβάζει. Ο κίνδυνος είναι ένας feedback loop: η write-back σας πυροδοτεί το ίδιο webhook που ενεργοποίησε τον handler σας, το οποίο γράφει ξανά, για πάντα. Αποτρέψτε το με ένα idempotency key (παράκαμψη αλλαγών που έχετε ήδη εφαρμόσει) και μια source flag (αγνόηση inbound events που προκαλούνται από το δικό σας εργαλείο).

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" },
    })
  );
}

Το μοτίβο είναι μικρό, αλλά η παράλειψή του είναι ο τρόπος με τον οποίο ένας συγχρονισμός διπλασιάζει quietly τον όγκο writes σας overnight. Μόλις τα δεδομένα είναι clean και προς τις δύο κατευθύνσεις, οι ομάδες συχνά τα τροφοδοτούν downstream σε έναν AI SDR pipeline ή σε ένα reporting layer. Το tutorial ενσωμάτωσης HubSpot της Nango είναι μια solid Node-only αναφορά αν θέλετε μια δεύτερη ματιά στον two-way sync, αν και θα χρειαστεί να portarετε την ιδέα loop-prevention μόνοι σας.

Να Κατασκευάσετε Αυτό In-House ή Να Προσλάβετε έναν Partner Ενσωμάτωσης;

Κατασκευάστε in-house όταν ο συγχρονισμός είναι μικρός, σταθερός και owned: μια one-way ροή, μια χούφτα αντικείμενα και ένας engineer που μπορεί να απορροφήσει τις breaking changes του HubSpot περίπου δύο φορές τον χρόνο. Προσλάβετε έναν partner όταν χρειάζεστε bidirectional sync, μοντελοποίηση custom-object, ή όταν κανείς στην ομάδα δεν μπορεί να αναλάβει τη συνεχή συντήρηση. Ο αποφασιστικός παράγοντας σπάνια είναι η αρχική κατασκευή· είναι ποιος το παρακολουθεί σε ένα χρόνο από τώρα.

Εδώ είναι μια ειλικρινής checklist. Κατασκευάστε το μόνοι σας αν: η κατεύθυνση είναι one-way, συγχρονίζετε standard objects, έχετε έναν developer που μπορεί να φιλοξενήσει ένα endpoint webhook, και κάποιος θα παρατηρήσει όταν ένα payload αρχίζει να αποτυγχάνει. Όλα τα παραπάνω είναι το blueprint σας.

Προσλάβετε έναν partner αν: χρειάζεστε two-way sync με loop prevention across several objects, μοντελοποιείτε custom objects με typed associations, συνδέετε πολλά συστήματα (HubSpot plus ένα ERP plus billing), ή το άτομο που θα το συντηρούσε είναι ήδη at capacity. Το HubSpot χρησιμοποιates date-based API versioning με breaking changes μόνο περίπου δύο φορές τον χρόνο, το οποίο ακούγεται gentle μέχρι να πέσει ένα κατά την πιο busy εβδομάδα σας και δεν υπάρχει owner. Αυτή η ουρά συντήρησης, όχι το πρώτο deploy, είναι αυτό που quietly βυθίζει τις εσωτερικές ενσωματώσεις. Αν προτιμάτε να μην το αναλάβετε εσείς, εκεί μπαίνουν οι υπηρεσίες προσαρμοσμένης ενσωμάτωσης CRM.

Κύρια Συμπεράσματα

• Δεν υπάρχει πια κλειδί HubSpot API. Χρησιμοποιήστε ένα token πρόσβασης ιδιωτικής εφαρμογής για ένα εσωτερικό εργαλείο ενός λογαριασμού· το OAuth είναι μόνο για δημόσιες, πολυλογαριασμικές εφαρμογές.
• Επικυρώστε πάντα το X-HubSpot-Signature-v3 πριν εμπιστευτείτε ένα payload webhook. Ανακατασκευάστε το source string με το full target URL.
• Σεβαστείτε το cap 4 req/s CRM Search και κάντε batch large writes σε chunks των 100 με backoff 429.
• Προτιμήστε webhooks αντί για polling για συγχρονισμό πραγματικού χρόνου, και μια ενσωμάτωση HubSpot είναι ένα κομμάτι ενός ευρύτερου stack AI tools for business.

Κολλήσατε στην πλευρά συντήρησης, ή θέλετε ένα δεύτερο ζευγάρι μάτια πριν κάνετε ship; Κλείστε μια δωρεάν consultation ενσωμάτωσης. Χωρίς πίεση είτε έτσι είτε αλλιώς· ο παραπάνω κώδικας είναι δικός σας για εκτέλεση ανεξάρτητα.

Σχετικά με τον Συγγραφέα

Ο Mert Batur Gurbuz είναι Συνιδρυτής της Techsy.io, όπου η ομάδα παραδίδει AI agents, συστήματα αυτοματοποίησης και voice/SDR pipelines για B2B πελάτες. Σπουδάζει στο Πανεπιστήμιο του Birmingham και γράφει για το LLM tooling stack που η ομάδα της Techsy χρησιμοποιεί πραγματικά σε production. Διαπιστευτήρια: Συνιδρυτής, Techsy.io, Πανεπιστήμιο του Birmingham. Συνδεθείτε στο LinkedIn.

Συχνές Ερωτήσεις

Χρειάζομαι ακόμα κλειδί HubSpot API το 2026;

Όχι. Το HubSpot απέσυρε τα στατικά κλειδιά API στις 30 Νοεμβρίου 2022 και δεν υποστηρίζονται πλέον καθόλου. Η autoComplete συνεχίζει να προτείνει "hubspot api key" από συνήθεια, αλλά δεν υπάρχει τίποτα για ανάκτηση. Για ένα εσωτερικό εργαλείο ενός λογαριασμού, δημιουργήστε μια ιδιωτική εφαρμογή στις Ρυθμίσεις και χρησιμοποιήστε το token πρόσβασής της αντί αυτού.

Ποια είναι η διαφορά μεταξύ ενός token ιδιωτικής εφαρμογής και του OAuth για το HubSpot;

Ένα token πρόσβασης ιδιωτικής εφαρμογής είναι ένα στατικό διαπιστευτήριο για έναν μόνο λογαριασμό HubSpot, χωρίς λήξη και χωρίς ροή refresh, ιδανικό για ένα εσωτερικό εργαλείο. Το OAuth 2.0 είναι για δημόσιες, πολυλογαριασμικές εφαρμογές που άλλες εταιρείες εγκαθιστούν στα δικά τους portals· τα tokens του λήγουν σε περίπου έξι ώρες και απαιτούν κύκλο refresh.

Ποια είναι τα rate limits του API του HubSpot το 2026;

Οι ιδιωτικές εφαρμογές λαμβάνουν περίπου 10 αιτήματα ανά δευτερόλεπτο (100 ανά 10 δευτερόλεπτα σε Free/Starter, 190 σε Pro/Enterprise) με ημερήσιο cap 250.000 έως 1.000.000. Το CRM Search API έχει ξεχωριστό cap στα 4 αιτήματα ανά δευτερόλεπτο, και τα batch endpoints δέχονται μέγιστο 100 εγγραφές ανά αίτημα.

Πώς επικυρώνω μια υπογραφή webhook του HubSpot;

Χρησιμοποιήστε τη συνταγή v3: απορρίψτε αιτήματα όπου το X-HubSpot-Request-Timestamp είναι παλαιότερο από πέντε λεπτά, στη συνέχεια κατασκευάστε ένα source string από method plus full target URL plus raw body plus timestamp. Εφαρμόστε HMAC-SHA256 με το app secret σας, encode το αποτέλεσμα σε base64 και συγκρίνετέ το με το X-HubSpot-Signature-v3 σε constant time.

Ποιο HubSpot SDK πρέπει να χρησιμοποιήσω, Node ή Python;

Και τα δύο είναι επίσημα και συντηρούνται. Το Node χρησιμοποιεί @hubspot/api-client (v14) και το Python χρησιμοποιεί hubspot-api-client (v12). Εκθέτουν το ίδιο v3 CRM object model, οπότε επιλέξτε whichever matches το stack σας. Αυτός ο οδηγός παραδίδει identically auth και κώδικα επικύρωσης υπογραφής και στις δύο γλώσσες.

Πώς συγχρονίζω το HubSpot με ένα προσαρμοσμένο εσωτερικό εργαλείο σε πραγματικό χρόνο;

Καταχωρήστε μια subscription webhook στην ιδιωτική σας εφαρμογή για το αντικείμενο και το event που σας ενδιαφέρει, στη συνέχεια φιλοξενήστε ένα HTTPS endpoint στο οποίο το HubSpot POSTάρει όταν συμβαίνει μια αντίστοιχη αλλαγή. Επικυρώστε την υπογραφή, στη συνέχεια γράψτε την αλλαγή στο εσωτερικό σας εργαλείο. Κάντε polling μόνο όταν καμία subscription webhook δεν καλύπτει αυτό που χρειάζεστε.

Τι είναι ένα HubSpot Service Key και πρέπει να το χρησιμοποιήσω;

Ένα Service Key είναι ένα διαπιστευτήριο επιπέδου λογαριασμού, μόνο για δεδομένα, που το HubSpot έβαλε σε public beta τον Φεβρουάριο του 2026. Στοχεύει σε server-side jobs που αγγίζουν μόνο δεδομένα. Για ένα standard εσωτερικό εργαλείο σήμερα, ένα token πρόσβασης ιδιωτικής εφαρμογής είναι ακόμα το safer, better-documented default· αντιμετωπίστε τα Service Keys ως beta μέχρι να graduate.

Μπορώ να δοκιμάσω μια ενσωμάτωση HubSpot χωρίς να αγγίξω το production;

Ναι. Δημιουργήστε ένα developer sandbox του HubSpot και δείξτε το token της ιδιωτικής σας εφαρμογής σε αυτό. Τα scopes, το object model, τα webhooks και τα rate limits συμπεριφέρονται ίδια όπως στο production, έτσι μπορείτε να δημιουργήσετε test contacts και να πυροδοτήσετε webhooks χωρίς να αφήνετε junk records για την ομάδα πωλήσεών σας να καθαρίσει αργότερα.

Πόσες εγγραφές μπορεί να δεχτεί το batch API του HubSpot ταυτόχρονα;

Τα batch endpoints (POST /crm/v3/objects/{objectType}/batch/create και τα update και upsert siblings του) δέχονται μέγιστο 100 εγγραφές ανά αίτημα. Χωρίστε μεγαλύτερα payloads σε ομάδες των 100. Το παλαιότερο ceiling "10 εγγραφών για επαφές" που κάποια tutorials ακόμα αναφέρουν έχει αφαιρεθεί· το 100 είναι το τρέχον across object types.

Να κατασκευάσω αυτό in-house ή να προσλάβω έναν agency;

Κατασκευάστε in-house όταν ο συγχρονισμός είναι one-way, χρησιμοποιεί standard objects και έχει έναν owner που μπορεί να απορροφήσει τις twice-a-year breaking changes του HubSpot. Προσλάβετε έναν partner για bidirectional sync, μοντελοποίηση custom-object, ή όταν κανείς δεν μπορεί να αναλάβει τη συντήρηση. Το πρώτο deploy είναι εύκολο· το έτος upkeep μετά από αυτό είναι το πραγματικό κόστος.