HubSpot | Nova lógica de transferência — Eventos Personalizados e Workflows
1. O que mudou na lógica de transbordo do HubSpot?
Em fevereiro de 2026, o HubSpot lançou novas funcionalidades que nos permitem evoluir a lógica de transferência de
tickets para N2. Com isso, migramos o fluxo de transbordo para essa nova abordagem, tornando a funcionalidade mais
resiliente, rastreável e observável.
As principais melhorias que essa evolução traz:
- Maior resiliência: o fluxo agora passa inteiramente por APIs e automações oficiais do HubSpot, reduzindo pontos de
falha.
- Rastreabilidade: cada transferência gera eventos auditáveis diretamente na plataforma, facilitando a investigação de
qualquer ocorrência.
- Observabilidade: conseguimos monitorar com mais precisão quantas transferências são concluídas com sucesso e
identificar rapidamente qualquer desvio.
2. Como funciona a nova lógica de transbordo?
Quando a ClaudIA decide transbordar o ticket para N2, o sistema agora:
1. Busca o ID do ticket associado à conversa no HubSpot.
2. Dispara um Evento Personalizado via API oficial do HubSpot, referenciando esse ticket.
3. Um Workflow configurado no HubSpot é ativado automaticamente ao receber esse evento.
4. O Workflow executa a transferência, atribuindo o ticket ao agente ou equipe de N2 configurados.
Nenhuma autenticação extra é necessária, todo o fluxo passa pelas APIs e automações oficiais da plataforma.
3. Preciso fazer algo no meu HubSpot?
Sim. Para que o novo fluxo funcione, é necessário criar no seu HubSpot:
- 1 Workflow de notificação de criação de ticket — envia o ID do ticket ao nosso sistema no momento em que ele é
criado (único por integração).
- 1 Evento Personalizado por fluxo de transbordo — recebe o sinal da ClaudIA para iniciar a transferência.
- 1 Workflow de transbordo baseado nesse evento por fluxo de transbordo — executa a atribuição para o agente ou equipe
de N2.
⚠️ Para clientes que utilizam a versão Inbox (e não Helpdesk), são necessários dois workflows adicionais. Veja a seção 7
para mais detalhes.
4. Por que precisamos de um evento de criação de ticket enviado ao nosso webhook?
Para disparar o transbordo corretamente, o sistema precisa conhecer o ID do ticket no HubSpot (hs_ticket_id) associado à
conversa em andamento.
O HubSpot não disponibiliza um método oficial na API para obter o ID do ticket a partir do ID de uma conversa
(threadId). Ou seja: quando a ClaudIA está atendendo e precisa transbordar o ticket, não é possível simplesmente
consultar a API do HubSpot e perguntar "qual ticket está associado a essa conversa?" de forma direta e confiável.
Para resolver isso, utilizamos um evento enviado pelo próprio HubSpot ao nosso webhook no momento em que o ticket é
criado. Esse evento carrega o threadId da conversa e o hs_ticket_id do ticket recém-criado, permitindo que armazenemos
essa associação do nosso lado e a utilizemos durante o transbordo.
⚠️ Sem esse evento, o sistema não consegue identificar com certeza o ticket correto e o transbordo via evento
personalizado pode falhar.
4.1. Como configurar o Workflow de notificação de criação de ticket
- Acesse Automações → Fluxos de Trabalho.
- Crie um workflow baseado em Ticket.
- Configure o gatilho: "Quando um ticket é criado".
- Adicione a ação "Enviar webhook" e configure com a URL fornecida pela Cloud Humans.
- O payload deve incluir o ID do ticket (hs_ticket_id) e o ID da conversa associada (threadId).
- Ative o Workflow.
Esse workflow precisa existir uma única vez por integração, independentemente de quantos fluxos de transbordo você
tiver.
5. Como configurar o Evento Personalizado de transbordo no HubSpot
O Evento Personalizado é o gatilho que a Cloud Humans utiliza para avisar o HubSpot que um transbordo deve acontecer.
5.1. Criar o Evento Personalizado
- Acesse Configurações → Gerenciamento de dados → Eventos personalizados.
- Clique em "Criar evento personalizado".
- Dê um nome claro ao evento (ex.: transbordo_para_n2).
- Adicione a propriedade obrigatória: objectId (tipo: Número).
- Salve o evento.
⚠️ Após criar o evento, copie o nome interno gerado pelo HubSpot (formato pe12345_nome_do_evento) e envie para o time da
Cloud Humans — ele é necessário para a configuração do nosso lado.
5.2. Informar o nome interno do evento à Cloud Humans
Após a criação, envie para o seu Customer Success:
- O nome interno do Evento Personalizado criado.
- Confirmação de que o evento está ativo.
6. Como configurar o Workflow de Transbordo no HubSpot
O Workflow é a automação responsável por mover o ticket para a equipe humana quando o evento de transbordo é recebido.
6.1. Criar o Workflow
- Acesse Automações → Fluxos de Trabalho.
- Clique em "Criar fluxo de trabalho" e selecione "Baseado em evento personalizado".
- Selecione o evento criado na seção 5.
6.2. Configurar a ação de atribuição
- Adicione a ação "Atribuir proprietário do ticket".
- Selecione o agente ou equipe de N2 de destino.
- Ative obrigatoriamente a opção "Substituir qualquer proprietário do ticket existente".
⚠️ Sem ativar essa opção, tickets que já possuem um proprietário atribuído não serão transferidos.
6.3. Ativar o Workflow
- Salve e clique em "Ativar".
7. Configuração adicional para clientes que usam a versão Inbox
A nova lógica de transbordo funciona com a versão Helpdesk do HubSpot, que já associa automaticamente um ticket a cada
conversa. Clientes que ainda utilizam a versão Inbox precisam configurar dois workflows adicionais para garantir essa
associação.
⚠️ Na versão Inbox, cada conversa deve ter no máximo um ticket associado. Se houver mais de um ticket por conversa, o
sistema não conseguirá identificar qual utilizar e o transbordo poderá falhar.
7.1. Workflow: criar ticket ao iniciar uma conversa
- Acesse Automações → Fluxos de Trabalho.
- Crie um workflow baseado em Conversa.
- Configure o gatilho para criar o ticket assim que a conversa entrar pra a Claudia ou caso já tenha um fluxo que faça
essa criação, deve ser ajustado pra nos enviar o webhook de criação.
- Adicione a ação "Criar ticket" e configure os campos necessários (pipeline, estágio inicial, etc.).
- Ative o Workflow.
7.2. Workflow: associar conversa ao proprietário do ticket
- Crie um segundo workflow baseado em conversas.
- Configure o gatilho: Ticket (Objeto Associado)".
- A última mensagem é um comentário do thread é igual a Verdadeiro
- Proprietário do ticket sempre foi qualquer um dos Claudia Cloud Humans
- Adicione a ação "Revezar registro para o proprietário" e escolha suas opções de transferência.
- Ative o Workflow.
8. E se eu tiver mais de um fluxo de transbordo?
Operações com múltiplos destinos de N2 (ex.: suporte técnico, financeiro, comercial) precisam de um Evento Personalizado
e um Workflow para cada fluxo de transbordo.
- Repita as configurações das seções 5 e 6 para cada fluxo.
- Informe todos os nomes internos dos eventos criados para o time da Cloud Humans.
O Workflow de notificação de criação de ticket (seção 4) não precisa ser duplicado — ele é único por integração.
9. Uso de "ticket infinito" — reinscrição no Workflow
Alguns clientes utilizam a configuração de ticket infinito, onde um mesmo ticket é reutilizado em múltiplos atendimentos
ao longo do tempo. Nesse cenário, o fluxo de transbordo pode precisar ser acionado mais de uma vez para o mesmo ticket.
Por padrão, os Workflows do HubSpot não permitem que o mesmo registro seja inscrito novamente após já ter passado pelo
fluxo. Para habilitar isso:
- Abra o Workflow de Transbordo.
- Acesse Configurações (ícone de engrenagem).
- Ative a opção "Permitir que registros sejam reinscritos".
É necessário falar com o nosso time se a sua operação utiliza ticket infinito e se essa configuração se aplica ao seu
caso.
