Connettore HubSpot

Connettore HubSpot

Collega il tuo HubSpot CRM a Brevo tramite Tajo per una sincronizzazione bidirezionale dei contatti, tracciamento dei deal, dati di engagement e automazione marketing unificata tra entrambe le piattaforme.

Panoramica

Funzionalità

• Sincronizzazione bidirezionale dei contatti - Mantieni i contatti sincronizzati tra HubSpot e Brevo in tempo reale
• Tracciamento pipeline deal - Sincronizza gli stage e i valori dei deal per la segmentazione basata sui ricavi
• Sincronizzazione dati azienda - Associa i contatti ai record aziendali e ai dati firmografici
• Integrazione ticket - Traccia i ticket di supporto per il customer health scoring
• Tracciamento engagement - Sincronizza aperture email, click, riunioni, chiamate e note
• Supporto oggetti personalizzati - Mappa gli oggetti personalizzati HubSpot agli attributi Brevo
• Trigger workflow - Usa i cambiamenti di lifecycle stage HubSpot per attivare automazioni Brevo
• Eventi webhook - Notifiche in tempo reale per i cambiamenti dei dati CRM

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account HubSpot (Free, Starter, Professional o Enterprise)
2. Una private app o un’app OAuth HubSpot con gli scope richiesti
3. Un account Brevo con accesso API
4. Un account Tajo

Autenticazione

Access Token Private App (consigliato)

Crea una private app in HubSpot per l’accesso diretto alle API con controllo granulare degli scope.

1. Vai in HubSpot Impostazioni > Integrazioni > Private Apps
2. Crea una nuova private app
3. Configura gli scope richiesti
4. Copia l’access token

curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

OAuth 2.0

Usa OAuth 2.0 per integrazioni multi-account che richiedono l’autorizzazione dell’utente.

# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}

Scope richiesti

crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read

Configurazione

Setup di base

connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12

Mappatura dei campi

Mappa le proprietà HubSpot agli attributi di contatto Brevo:

Mappatura proprietà personalizzate

field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT

Endpoint API

Oggetti CRM

Associazioni

Engagement

Eventi

Eventi contatto

Eventi deal

Eventi azienda

Esempi di codice

Inizializza il connettore

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

Esegui sincronizzazione contatti

// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }

Gestisci eventi webhook

// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

  res.status(200).send('OK');
});

Limiti di velocità

HubSpot applica i limiti di velocità per private app o app OAuth:

Limiti aggiuntivi:

• Search API: 5 richieste/secondo per app
• Operazioni batch: 100 record per richiesta batch
• Limite giornaliero: 500.000 richieste/giorno (app OAuth)

Risoluzione dei problemi

Problemi comuni

Modalità debug

Abilita il logging dettagliato:

connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true

Testa la connessione

tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered

Best practice

1. Usa le private app invece delle API key - Le API key sono deprecate; usa le private app per maggiore sicurezza
2. Implementa la sync bidirezionale con attenzione - Evita loop infiniti tracciando la sorgente di sync
3. Mappa i lifecycle stage - Usa i lifecycle stage HubSpot per segmentare i contatti in Brevo
4. Richieste API in batch - Usa gli endpoint batch per operazioni in blocco e rimani entro i limiti
5. Monitora la consegna dei webhook - Imposta logica di retry e gestione delle dead letter
6. Usa la sync incrementale - Sincronizza solo i record modificati usando la proprietà lastmodifieddate

Sicurezza

• Private App Token - Access token con scope granulari
• OAuth 2.0 - Autorizzazione standard del settore con rotazione dei refresh token
• Firme webhook - Verifica firma basata su HMAC (v3)
• Cifratura TLS - Tutte le comunicazioni API cifrate in transito
• Permessi con scope - Accesso agli scope minimi richiesti per integrazione

Risorse correlate

• Documentazione API HubSpot
• Guida autenticazione HubSpot
• Connettore Salesforce
• Skill Customer Sync
• API Contatti Brevo