Integracao Zenvia → HubSpot

Antes de falar de fluxos, um resumo rapido do que ja foi confirmado em calls anteriores com a Zenvia (15/01 e 21/01):

Neste fluxo, construimos um middleware nosso que fica entre a Zenvia e o HubSpot. Ele recebe todos os eventos, processa a logica e grava no CRM. E o plano original da Estimativa V4.1.

2.1 O que viabiliza este fluxo

O middleware e uma aplicacao Node.js/Express controlada por nos. Nao depende de nenhum recurso especial do HubSpot — precisa apenas da API padrao do HubSpot (qualquer plano com acesso a API: Marketing Hub, Sales Hub, etc.).

Capacidades do middleware:

• Endpoint HTTP proprio — recebe POST da Zenvia (webhook)
• Chamadas ilimitadas para APIs externas (Zenvia GET /contacts, HubSpot API)
• Sem limite de tempo de execucao (pode processar logica complexa)
• Fila propria (Bull/Redis, SQS) com retry, Dead Letter Queue, idempotencia
• Codigo versionado em Git — testavel, debugavel, auditavel
• Pode rodar em Railway, Render, AWS, GCP ou qualquer cloud

2.2 Passo a passo (explicacao simplificada)

PASSO 1    Cliente manda WhatsApp
           |
PASSO 2    ZENVIA recebe a mensagem e o atendimento acontece
           |
PASSO 3    Quando algo muda (novo atendimento, mensagem, vendedor atribuido, fechou)
           a ZENVIA automaticamente envia um aviso (POST) para o NOSSO MIDDLEWARE
           |
PASSO 4    NOSSO MIDDLEWARE recebe o aviso e faz:
           a) Valida que o aviso e legitimo (autenticacao)
           b) Busca dados completos do contato na ZENVIA (GET /contacts)
           c) Aplica regra: esse vendedor e o dono? Ja tem negocio aberto?
           d) Grava tudo no HUBSPOT: contato, negocio, conversa, vendedor
           |
PASSO 5    HUBSPOT tem os dados. Equipe ve no CRM.

Detalhando cada passo:

1. Cliente manda WhatsApp

Uma pessoa interessada em seguro pet envia mensagem pelo WhatsApp da PetLove. A Zenvia e quem recebe essa mensagem na plataforma de atendimento.

2. Zenvia processa o atendimento

O vendedor da PetLove atende pelo painel da Zenvia. O atendimento pode passar por fila, ser distribuido a um vendedor, receber mensagens, e eventualmente ser encerrado.

3. Zenvia envia webhooks para nosso middleware

Cada vez que algo muda (nova conversa, mensagem, vendedor atribuido, conversa fechada), a Zenvia automaticamente faz um POST para a URL do nosso middleware. Esse POST contem: ID da conversa, tipo do evento, ID do contato.

4. Middleware processa o evento

Nosso middleware recebe o POST e executa toda a logica:

• a) Valida autenticacao (confirma que veio da Zenvia)
• b) Coloca na fila (para evitar perda em caso de falha)
• c) Busca dados completos do contato na Zenvia (GET /contacts/{id})
• d) Verifica regras: janela 24h, carteira 15 dias, 1 negocio por vez
• e) Mapeia vendedor: userId Zenvia → email → ownerId HubSpot
• f) Cria/atualiza no HubSpot: Contact, Deal, Communication, Atendimento, Owner

5. HubSpot tem os dados

A equipe comercial abre o HubSpot e ve tudo atualizado: contato com dados do WhatsApp, negocio criado, conversa registrada na timeline, vendedor correto como owner.

2.3 Diagrama

  +----------+    POST webhook     +-------------------------+     POST API      +-----------+
  |          | ------------------> |                         | ----------------> |           |
  |  ZENVIA  |                     |  MIDDLEWARE (Node.js)   |                   |  HUBSPOT  |
  |          | <------------------ |                         |                   |    CRM    |
  +----------+   GET /contacts/{id}|  * Valida webhook       |                   |           |
                                   |  * Busca contato Zenvia |                   | * Contact |
               (chamado pelo       |  * Regras ownership     |                   | * Deal    |
                Middleware)        |  * Idempotencia / fila  |                   | * Comm.   |
                                   |  * Cria objetos HubSpot |                   | * Owner   |
                                   +-------------------------+                   +-----------+

2.4 Quem faz o que

2.5 Pros

2.6 Contras

Neste fluxo, a Zenvia envia webhooks diretamente para o HubSpot, que processa tudo internamente usando Workflows com Custom Code. Nao existe middleware externo — e 100% Zenvia + HubSpot.

3.1 O que o HubSpot oferece que viabiliza este fluxo

Analise baseada na documentacao oficial do HubSpot (developers.hubspot.com + knowledge.hubspot.com). Tres capacidades-chave:

① Receber webhooks de apps externos

O HubSpot gera uma URL propria que aceita POST de qualquer app externo. Quando recebe o POST, dispara um Workflow automaticamente.

• 1. Criar Workflow — No HubSpot → Automation → Workflows → New workflow.
• 2. Escolher trigger "When a webhook is received" — Na secao "Custom events & external events". O HubSpot gera uma URL unica.
• 3. Configurar URL no Zenvia — Na plataforma da Zenvia, cadastramos essa URL como destino dos webhooks. A Zenvia envia POST com application/json diretamente para o HubSpot.
• 4. HubSpot mapeia campos e dispara acoes — O JSON e parseado, campos sao mapeados para propriedades do contato, e o workflow executa as acoes configuradas (Custom Code, etc.).

② Custom Code Actions (codigo serverless dentro do Workflow)

Dentro de um Workflow, e possivel rodar codigo Node.js ou Python como serverless function (AWS Lambda). Pode chamar APIs externas (ex: Zenvia GET /contacts) e a API do HubSpot internamente.

• Chamar APIs externas com axios (ex: GET /contacts na Zenvia)
• Usar @hubspot/api-client para criar/atualizar CRM internamente
• Guardar secrets (tokens) em variaveis de ambiente seguras
• Retornar dados para o proximo passo do workflow (data outputs)
• Conectar com Redis, MySQL, MongoDB, Google APIs, AWS SDK

③ Send a Webhook (Workflow → API externa)

Uma acao dentro do Workflow que faz POST ou GET para qualquer URL externa, com autenticacao (API key ou HMAC), retry automatico por ate 3 dias.

• POST: envia dados do HubSpot para API externa
• GET: busca dados de API externa e injeta no workflow
• Autenticacao: API key (header/query) ou request signature (HMAC)
• Retry: automatico por ate 3 dias, respeita Retry-After em 429

3.2 Passo a passo — o que funciona (contatos JA existentes no HubSpot)

Para contatos que JA EXISTEM no HubSpot (ex: ja foram importados, ja vieram por formulario, ja foram cadastrados manualmente), o fluxo funciona 100% sem nenhum middleware externo.

PASSO 1    Cliente manda WhatsApp (contato JA EXISTE no HubSpot)
           |
PASSO 2    ZENVIA recebe a mensagem e o atendimento acontece
           |
PASSO 3    Quando algo muda (novo atendimento, mensagem, vendedor atribuido, fechou)
           a ZENVIA envia POST diretamente para a URL do HUBSPOT
           |
PASSO 4    HUBSPOT recebe o webhook, encontra o contato pela propriedade unica
           (ex: telefone), e DISPARA o WORKFLOW automaticamente
           |
PASSO 5    Dentro do Workflow, um CUSTOM CODE (Node.js) roda:
           a) Busca dados completos na ZENVIA (GET /contacts)
           b) Aplica regras de negocio (ownership, janela 24h)
           c) Cria o negocio, grava a conversa, seta o vendedor
           |
PASSO 6    HUBSPOT tem os dados. Equipe ve no CRM.

Detalhando cada passo:

1. Cliente manda WhatsApp

Uma pessoa interessada em seguro pet envia mensagem pelo WhatsApp da PetLove. A Zenvia e quem recebe essa mensagem na plataforma de atendimento. Esse cliente ja foi cadastrado no HubSpot anteriormente (importacao, formulario, etc.).

2. Zenvia processa o atendimento

O vendedor da PetLove atende pelo painel da Zenvia. O atendimento pode passar por fila, ser distribuido a um vendedor, receber mensagens, e eventualmente ser encerrado.

3. Zenvia envia webhook DIRETO para o HubSpot

Cada vez que algo muda (nova conversa, mensagem, vendedor atribuido, conversa fechada), a Zenvia faz um POST diretamente para a URL gerada pelo HubSpot. Esse POST contem: ID da conversa, tipo do evento, telefone do contato.

4. HubSpot recebe e dispara Workflow

O HubSpot recebe o webhook, procura um contato com a propriedade unica correspondente (ex: campo phone = numero do WhatsApp). Como o contato JA EXISTE, o Workflow e disparado automaticamente.

5. Custom Code processa dentro do HubSpot

Dentro do Workflow, um bloco de Custom Code (Node.js) roda:

• a) Usa axios para chamar a Zenvia: GET /contacts/{id} — busca dados completos
• b) Aplica regras de negocio (ownership, janela 24h)
• c) Mapeia vendedor: userId Zenvia → email → ownerId HubSpot
• d) Usa @hubspot/api-client para criar: Deal, Communication, Atendimento, Owner

Tudo acontece DENTRO do HubSpot, zero middleware externo.

6. HubSpot tem os dados

A equipe comercial abre o HubSpot e ve tudo atualizado: contato, negocio, conversa registrada, vendedor correto. Igual ao Fluxo A — o resultado final e o mesmo.

3.3 O que NAO funciona — Limitacao com contatos novos

CENARIO: Contato NOVO (primeira conversa no WhatsApp - nunca esteve no HubSpot)

PASSO 1    Cliente NOVO manda WhatsApp
           |
PASSO 2    ZENVIA recebe e atende normalmente
           |
PASSO 3    ZENVIA envia POST para a URL do HUBSPOT
           |
PASSO 4    HUBSPOT recebe, procura contato com phone = +5511999...999
           → NAO ENCONTRA (contato nunca existiu)
           → WEBHOOK IGNORADO
           → Nenhum workflow dispara
           → Dados perdidos silenciosamente

O que isso significa na pratica:

• Se o contato e novo (primeira conversa no WhatsApp, nunca cadastrado no HubSpot) → dados PERDIDOS
• O HubSpot nao avisa, nao gera erro, nao registra — simplesmente ignora
• Para que funcione, o contato PRECISA existir no HubSpot ANTES do webhook chegar
• Contatos que ja vieram por formulario, importacao ou cadastro manual → funcionam normalmente

Formas de garantir que o contato exista previamente:

• Importacao periodica de contatos da Zenvia para o HubSpot (manual ou agendada)
• Formulario de captacao de leads que ja cadastra no HubSpot antes de ir para a Zenvia
• Integracao via outra ferramenta (ex: RD Station → HubSpot) que cria o contato antes
• Criar contatos manualmente no HubSpot a medida que chegam na Zenvia

3.4 Diagrama

                POST webhook (direto)
  +----------+                        +-------------------------------------+
  |          | ---------------------> |  HUBSPOT (Operations Hub)           |
  |  ZENVIA  |                        |                                     |
  |          |                        |  1. Recebe webhook                  |
  +----------+                        |  2. Busca contato por prop. unica   |
       ^                              |     Encontrou → Workflow dispara    |
       |                              |     Nao encontrou → IGNORA         |
       |                              |  3. Custom Code (Node.js):          |
       |                              |     * axios: GET Zenvia /contacts   |
       |  GET /contacts/{id}          |     * Regras ownership (24h/15 d)   |
       +------------------------------+     * Cria Deal, Communication      |
          (chamado pelo Custom Code)  |     * Seta Owner (vendedor)         |
                                      |  4. Resultado:                      |
                                      |     * Contact (existente, atualiz.) |
                                      |     * Deal + Communication + Owner  |
                                      +-------------------------------------+

3.5 Quem faz o que

3.6 Pros

3.7 Contras

5.1 WhatsApp nativo do HubSpot (sem Zenvia)

O HubSpot tem integracao nativa com WhatsApp via Meta Cloud API. As mensagens aparecem direto na Inbox. Porem, isso exige migrar o numero do Zenvia para o Meta diretamente, eliminando o Zenvia como plataforma de atendimento (filas, roteamento, chatbot, distribuicao). Nao e viavel sem redesenhar a operacao da PetLove.

5.2 Zapier / Make como middleware

Sao plataformas de middleware visual (no-code). Funcionam para fluxos simples, mas a logica da PetLove e complexa: ownership com janela 24h/15 dias, idempotencia, multiplas APIs encadeadas (GET Zenvia → POST Contact → POST Deal → POST Communication → POST Association → Set Owner). Zapier/Make ficam frageis com essa complexidade, cobram por execucao (escala limitada), e nao oferecem fila/DLQ/retry adequado.

5.3 HubSpot Custom Channels API

API que faz mensagens da Zenvia aparecerem na Inbox de Conversas do HubSpot (como se fosse WhatsApp nativo). MAS: requer backend igualmente (e middleware). Nao e necessario para o MVP, que foca no CRM (contatos, negocios, timeline). Pode ser evolucao pos-MVP se quiserem conversas na Inbox.

Dois fluxos viaveis

Existem dois caminhos reais para integrar Zenvia → HubSpot. Ambos entregam o mesmo resultado para o usuario final (contato, negocio, conversa e vendedor no CRM). A diferenca esta em quem faz o trabalho pesado e quais requisitos de licenca sao necessarios:

Proximos passos

• Ja temos: Documentacao dos webhooks, payloads, fluxo push, GET /contacts, limitacoes v1 vs v2.
• Falta: Tokens (v2 e v1), plataforma para subscriptions, autenticacao de webhook, mapeamento de vendedores.
• Decisao: Definicao do fluxo (A ou B) depende do plano HubSpot da PetLove e da complexidade final da logica de ownership.

Decisao-chave