Última modificação: 11 de setembro de 2025
Usando eventos de aplicativos, você pode enviar dados de atividade aprimorados de seus sistemas externos diretamente para o HubSpot. Os dados de eventos de aplicativo são associados a registros do CRM e podem ser usados nas ferramentas de automação, análise e relatórios do HubSpot. Abaixo, saiba mais sobre como os eventos de aplicativo funcionam. Para começar a criar eventos de aplicativo em seu projeto:
Os eventos de aplicativo descritos nesta documentação destinam-se a aplicativos criados para o Marketplace de aplicativos usando projetos de desenvolvedor. Para criar relatórios para outros tipos de integrações, você pode usar eventos personalizados.

​
Como funcionam os eventos de aplicativo

Eventos são pontos de dados que capturam o que ocorreu em um momento específico, muitas vezes relacionado às ações do usuário, como enviar um formulário, enviar uma mensagem SMS ou exibir uma página. Ao contrário dos registros, que se destinam a mostrar o estado atual de uma entidade, os eventos podem dar uma melhor compreensão dos padrões de atividade, alterações comportamentais ao longo do tempo e outras tendências.
Os eventos de aplicativo são ideais quando seus dados:
  • Representam ações ou atividades que acontecem repetidamente.
  • Precisam ser analisados quanto a alterações ou volume ao longo do tempo.
  • Não precisam ser atualizados após a criação.
Em alto nível, um evento de aplicativo consiste em:
  • Definição de tipo de evento: um esquema JSON que define a estrutura, as propriedades e as regras de validação do evento. Isso inclui o nome do evento, o rótulo de exibição, o objeto do CRM de destino e as propriedades do evento. Os tipos de evento também incluem definições para modelos de exibição para renderização de linhas do tempo de registros do CRM. Os tipos de evento são definidos usando projetos de desenvolvedor.
  • Ocorrências de evento: instâncias individuais de eventos que contêm dados reais, validados em relação ao esquema de tipo de evento. Os dados de ocorrência de evento são enviados por meio da API de eventos do aplicativo e incluem o identificador de tipo de evento, valores de propriedade, carimbos de data/hora e metadados adicionais, bem como dados de referência do objeto do CRM para associação do registro do CRM.
Eventos de linha do tempo vs. eventos de aplicativoAnteriormente, o HubSpot liberava eventos de linhas do tempo para permitir que você apresentasse dados de eventos em linhas do tempo de objetos do CRM. Os eventos de aplicativo permitem essa mesma funcionalidade em uma lista expandida de objetos suportados, ao mesmo tempo em que estão disponíveis em outras ferramentas da HubSpot. Os eventos de aplicativo agora também têm sua própria página de índice, juntamente com eventos personalizados, fornecendo uma visão unificada das atividades de evento.As integrações de eventos de linhas do tempo existentes continuarão a funcionar e estarão visíveis nos mesmos locais que os eventos de aplicativo. No entanto, para criar novos tipos de evento ou fazer alterações em tipos existentes, você deve recriá-lo como um evento de aplicativo em seu projeto de desenvolvedor.

​
Objetos e ferramentas compatíveis

Ao definir um tipo de evento, você o configurará para associar a um objeto do CRM específico, permitindo que você vincule os dados do evento à sua origem, como os contatos que fazem logon no seu site. Ocorrências de eventos podem ser associadas a registros do CRM desse tipo. Os eventos de aplicativo podem ser associados aos seguintes objetos do CRM:
  • Contatos
  • Empresas
  • Negócios
  • Tickets
  • Objetos personalizados
  • Objetos de aplicativo
Os eventos de aplicativo podem ser usados nas seguintes ferramentas da HubSpot:
  • Interface de gerenciamento de eventos: veja e analise os dados de eventos de aplicativo no painel de eventos personalizados, juntamente com os dados de evento personalizado navegando até Gerenciamento de dados > Eventos personalizados em sua conta.
  • Linhas do tempo de registros do CRM: veja a atividade cronológica de eventos de aplicativo nas linhas do tempo de registros do CRM associados a ocorrências de eventos.
  • Ferramentas de relatório: use dados de eventos de aplicativo para criar relatórios personalizados, análises da jornada do cliente e conjuntos de dados para análise e visualização.
  • Pontuações de leads, listas e fluxos de trabalho: segmente seu banco de dados de CRM usando eventos para listas dinâmicas, pontuação de leads e fluxos de trabalho.

​
Práticas recomendadas

Ao criar tipos de evento:
  • Use nomes claros e descritivos para os tipos de evento e as propriedades, pois estes aparecerão como filtros nos fluxos de trabalho, nas listas, nos relatórios e no painel de eventos personalizados.
  • Escolha os tipos de propriedades apropriados (string, número, data e hora etc.) que correspondam aos seus dados e habilite a filtragem e a análise adequadas.
  • Inclua propriedades que serão úteis para gatilhos de segmentação, geração de relatórios e automação (por exemplo, valores de transação, funções de usuários, categorias de ação).
  • Crie tipos de evento tendo em mente casos de uso de relatórios e fluxos de trabalho, considerando como os usuários filtrarão e agruparão dados de evento.
  • Evite fazer alterações interruptivas em esquemas de tipo de evento existentes, pois isso pode interromper os fluxos de trabalho existentes e os relatórios que dependem da estrutura do evento.
Para manter dados de eventos de alta qualidade:
  • Revise todas as solicitações programáticas de dados de ocorrência de evento para garantir que sejam validadas adequadamente em relação ao esquema de tipo de evento.
  • Use formatação consistente para valores de propriedade de evento, especialmente para datas, números e dados categóricos.
  • Verifique se as ocorrências de evento estão associadas a Ids de registros do CRM válidos.
  • Monitore as taxas de sucesso de envio de eventos e respostas de erro.
  • Analise regularmente os dados de eventos nas linhas do tempo dos registros do CRM e no painel de eventos personalizados quanto à precisão.
Otimize o desempenho de envio de eventos:
  • Colocando várias ocorrências de evento em lote em solicitações únicas de API quando possível (até 500 eventos por lote).
  • Mantendo as cargas de ocorrência de evento otimizadas, incluindo apenas os dados necessários da propriedade.
  • Implementando lógica de repetição com retrocesso exponencial para envios de eventos que falharam.

​
Limitações

Lembre-se das limitações a seguir ao planejar e criar eventos de aplicativos.

​
Requisitos de versão

  • Eventos de aplicativo somente podem ser criados por meio da versão mais recente da plataforma de projeto do desenvolvedor (2025.2).
  • Para tipos de evento existentes, você pode continuar usando a v1 e a API de eventos de linha do tempo v3. No entanto, não é possível criar novos tipos de evento usando a v1 e as APIs v3.

​
Restrições de tipo de evento

  • As ocorrências de evento devem estar de acordo com o esquema de tipo de evento definido ou serão rejeitadas.
  • Alguns campos de tipo de evento não podem ser atualizados depois que o tipo de evento é criado (por exemplo, name e objectType).
  • Novos tipos de evento estão sujeitos a um processo de revisão antes de serem ativados.

​
Limitações de dados

  • As propriedades individuais estão limitadas a 510 KB, com o tamanho total de evento limitado a 1 MB.
  • Os eventos de aplicativo são destinados a provedores do Marketplace de aplicativos e somente funcionarão com aplicativos configurados para usar a autenticação OAuth. Os sistemas internos devem usar eventos personalizados.

​
Começando

Para começar a trabalhar com eventos de aplicativo, você precisará: