Automação na HubSpot com webhooks, workflows e código personalizado

Quando se fala em automação na HubSpot, a maioria das pessoas pensa nos workflows visuais, aqueles que o marketing monta arrastando blocos na tela. E eles são ótimos para muita coisa. Mas existe um andar acima, onde a automação encontra a API, e é nesse andar que moram os processos que realmente escalam: reagir a eventos em tempo real, criar fluxos por código, rodar lógica personalizada dentro deles.

Esse território é mais poderoso e também mais traiçoeiro. Um webhook mal tratado processa o mesmo evento duas vezes. Um workflow criado por API esbarra num detalhe que ninguém avisou. Uma ação de código estoura o tempo de execução no pior momento. Neste guia, vou organizar as três frentes da automação por API, webhooks, workflows e código personalizado, e mostrar os cuidados que separam uma automação que dorme tranquila de uma que acorda o time de madrugada.

Workflows pela Automation v4

Criar um workflow por API é um POST para a Automation v4, onde você define o tipo de fluxo, o critério de inscrição e a sequência de ações. Para fluxos baseados em contato, o type é CONTACT_FLOW, e PLATFORM_FLOW para os demais. Um padrão saudável é criar o fluxo desligado, com isEnabled em falso, e ligá-lo manualmente na interface só depois de revisar que ele faz o que deveria. Isso evita que um fluxo recém-criado comece a inscrever registros antes de você conferir a lógica. Vale notar que a Automation v4 está em beta e exige o escopo automation.

Um engano comum, e que vale corrigir, é achar que pela API você só cria inscrição baseada em filtro. Dá para criar as duas. Os critérios por filtro usam valor de propriedade e participação em lista, e os critérios por evento usam eventFilterBranches com unified events, por exemplo inscrever um contato quando ele envia um formulário específico. Como os payloads são detalhados e a API está em beta, muitos times ainda montam a estrutura do fluxo por API e ajustam os gatilhos mais complexos na interface, mas o gatilho de evento em si é criável por API.

Webhooks: reagir a eventos em tempo real

Webhooks são o jeito de a HubSpot avisar a sua integração no instante em que algo muda: um contato criado, um negócio que mudou de estágio, uma propriedade atualizada. Em vez de você ficar perguntando à HubSpot de tempos em tempos se algo mudou, ela te avisa. Isso torna a automação reativa e quase instantânea, o que é exatamente o que você quer para processos sensíveis a tempo, como rotear um lead quente para o vendedor certo na hora.

O cuidado central com webhooks é a idempotência, e ela não é opcional. O mesmo evento pode ser entregue mais de uma vez, por reenvios ou por instabilidade de rede. Se a sua integração não estiver preparada para isso, ela vai processar a mesma mudança duas vezes, criando duplicatas ou disparando o mesmo email repetido. Use o identificador do evento para reconhecer e ignorar entregas repetidas, responda rápido para a HubSpot não acumular reenvios, e valide a assinatura da requisição da HubSpot, o cabeçalho X-HubSpot-Signature calculado com o client secret do app, antes de processar qualquer coisa.

Código personalizado dentro do workflow

A ação de código personalizado é a ponte entre a simplicidade do workflow visual e a flexibilidade de programar. Ela roda dentro do fluxo, recebe dados do registro inscrito, usa secrets para guardar credenciais com segurança e pode chamar APIs externas. É perfeita para aquela lógica que os blocos prontos não cobrem, como calcular um valor a partir de regras complexas ou consultar um sistema de fora.

Mas ela tem limites que precisam ser respeitados. Há um teto de tempo de execução e de memória, e ações que demoram demais ou consomem demais simplesmente falham. A regra é manter o código curto, previsível e focado. Quando a lógica começa a ficar pesada, a bater nos limites ou a depender de muitos passos externos, é sinal de que aquilo deveria sair do workflow e virar uma integração externa dedicada, com mais controle e sem as amarras da ação de código.

Retries e filas de dead-letter

Integrações orientadas a evento falham de vez em quando, é da natureza delas. Uma chamada externa que não responde, um sistema de destino que está fora do ar por um minuto. O padrão robusto para lidar com isso é repetir com recuo progressivo: tentou e falhou, espera um pouco e tenta de novo, aumentando o intervalo a cada falha. Isso resolve as falhas transitórias, que são a maioria.

Para as falhas que persistem depois de algumas tentativas, entra a fila de dead-letter. Em vez de simplesmente perder o evento ou ficar tentando para sempre, você o manda para uma fila separada, onde ele fica registrado para reprocessamento manual depois. Assim, nenhum evento se perde no silêncio, e você tem visibilidade do que falhou e por quê. Uma automação sem dead-letter é uma automação que perde dados sem ninguém saber.

Webhooks de app contra notificações de workflow

Existe mais de um jeito de a HubSpot te avisar sobre uma mudança, e escolher o certo evita dor de cabeça. Os webhooks de app pertencem a um app e são o caminho robusto para reagir a eventos de CRM em escala, com controle fino sobre quais eventos você quer ouvir. Num app privado legado, você configura as assinaturas de webhook nas configurações do app, na interface; num app do novo developer platform, você as configura como código, onde o webhooks v3 funciona com token estático e o v4 com OAuth. Uma account service key não faz webhook. Já a ação de webhook dentro de um workflow é outra coisa, mais simples: um passo que envia uma chamada para um sistema externo em um ponto do fluxo.

A escolha depende do alcance. Se você quer ouvir todas as criações de contato do portal, o webhook de app é o lugar. Se você quer avisar um sistema só quando um negócio específico chega a um estágio específico, a ação de webhook no workflow resolve com menos esforço. Misturar os dois sem critério é o que gera aquela situação em que ninguém sabe mais de onde vem cada notificação.

Boas práticas que tornam a automação previsível

Além dos cuidados pontuais, algumas práticas gerais separam uma automação madura de uma improvisada. Registre logs de cada evento processado, com o identificador e o resultado, para conseguir investigar quando algo der errado. Responda ao webhook o mais rápido possível, fazendo o processamento pesado de forma assíncrona depois, para não segurar a conexão e provocar reenvios. E versione as suas automações como código, revisando mudanças antes de elas chegarem à produção.

Essas práticas não aparecem quando tudo funciona, mas são exatamente o que salva a operação quando algo quebra. Uma automação com logs claros e processamento assíncrono é depurável em minutos. Uma sem isso é uma caixa-preta que ninguém entende sob pressão. O custo de adotar essas práticas é baixo, e o retorno aparece no primeiro incidente que você resolve rápido em vez de passar a madrugada caçando.

Por que isso importa para a sua operação

Automação bem feita é o que permite uma operação crescer sem inchar o time na mesma proporção. Um lead que chega de madrugada e é roteado na hora, um negócio que muda de estágio e dispara a próxima ação sozinho, um dado que se atualiza em todos os sistemas sem ninguém digitar nada. Esses ganhos só se sustentam se a automação for confiável. Uma automação que processa eventos em duplicata ou que perde mensagens em silêncio é pior do que não ter automação, porque cria uma falsa sensação de controle.

Por isso os cuidados técnicos, idempotência, retries, dead-letter, não são preciosismo. Eles são o que torna a automação digna de confiança a ponto de a operação se apoiar nela para tomar decisões e tratar clientes. A diferença entre uma automação que escala e uma que vira fonte de retrabalho está justamente nesses detalhes que ninguém vê quando tudo funciona.

Na prática: o email que saía duas vezes

Uma operação tinha uma automação que, de vez em quando, mandava o mesmo email para o mesmo contato duas vezes, o que gerava reclamação e passava imagem de desorganização. A causa era um webhook sem tratamento de idempotência: quando a HubSpot reenviava um evento, a integração processava de novo, do zero, como se fosse a primeira vez.

A correção foi guardar o identificador de cada evento já processado e ignorar entregas repetidas. Os emails duplicados pararam imediatamente. O mesmo padrão foi estendido a todos os webhooks da operação, e de quebra o time ganhou visibilidade dos eventos que falhavam, que antes simplesmente sumiam. Um detalhe técnico pequeno resolveu um problema que os clientes percebiam.

Checklist de uma automação confiável

1. Os workflows criados por API nascem desligados, para revisão antes de ligar?
2. Os critérios de inscrição definidos por API, por filtro ou por evento, foram revisados antes de ligar?
3. Todo webhook trata idempotência, ignorando entregas repetidas pelo id do evento?
4. O endpoint de webhook valida a assinatura da HubSpot antes de processar?
5. As ações de código personalizado respeitam os limites de tempo e memória?
6. Há recuo progressivo nos retries e uma fila de dead-letter para falhas persistentes?

Perguntas frequentes

Posso criar gatilhos de evento de workflow pela API?

Sim. A Automation v4 suporta tanto inscrição por filtro (valor de propriedade, participação em lista) quanto por evento, via eventFilterBranches com unified events, por exemplo inscrever um contato num envio de formulário. A API está em beta e os payloads são detalhados, então alguns times ainda finalizam os gatilhos mais complexos na interface, mas o gatilho de evento em si é criável por API.

Por que tratar idempotência em webhooks?

Porque o mesmo evento pode ser entregue mais de uma vez. Usar o id do evento para ignorar duplicados evita processar a mesma mudança duas vezes, o que causaria emails repetidos ou registros duplicados.

Quando migrar a lógica do código personalizado para fora?

Quando ela bate nos limites de tempo ou memória da ação, fica complexa demais para manter dentro do workflow, ou depende de muitos passos externos. Aí uma integração externa dedicada é mais segura.

O que é uma fila de dead-letter?

É uma fila separada para onde vão os eventos que falharam mesmo depois de algumas tentativas. Em vez de perder o evento, você o registra para reprocessamento manual, garantindo visibilidade e que nada se perca em silêncio.

Como protejo meu endpoint de webhook?

Validando a assinatura da requisição da HubSpot, o cabeçalho X-HubSpot-Signature calculado com o client secret do app, antes de processar qualquer coisa, para garantir que a chamada veio mesmo da HubSpot, e respondendo rápido para a plataforma não acumular reenvios.

Devo criar o workflow ligado ou desligado pela API?

Desligado, com isEnabled em falso. Assim você revisa a lógica na interface antes de o fluxo começar a inscrever registros, evitando surpresas em produção.

Quer automações que reagem a eventos sem perder mensagem nem processar duplicado? Na Insight Sales desenhamos fluxos, webhooks e filas resilientes na HubSpot. Fale com a gente e descubra como podemos ajudar.