Última modificação: 11 de setembro de 2025
Para enviar dados de eventos de aplicativo para o HubSpot, primeiro você criará um tipo de evento usando um projeto de desenvolvedor. O tipo de evento é um esquema JSON que define a estrutura, as propriedades e as regras de validação para os dados de ocorrência do evento que você enviará. 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 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.

​
Pré-requisitos

Para incluir uma definição de tipo de evento de aplicativo no seu projeto:
  • Você deve usar a CLI da HubSpot versão 7.5.4 ou posterior. Você pode verificar a sua versão da CLI executando hs --version e atualize executando npm i -g @hubspot/cli@next.
  • Seu projeto deve ser implantado para que você possa atualizá-lo para incluir um componente de evento de aplicativo.

​
Definir arquivos de projeto

Se você criou anteriormente um aplicativo público com um evento de linha do tempo, saiba mais sobre como migrá-lo para a plataforma para desenvolvedores.
1

Configuração do aplicativo e estrutura do projeto

Para criar uma nova definição de tipo de evento de aplicativo em seu projeto, atualize seu arquivo de configuração de aplicativo hsmeta.json para incluir o escopo timeline no campo requiredScopes. Isso é necessário para que os dados de evento do aplicativo apareçam nas linhas do tempo dos registros do CRM. Os instaladores devem conceder esse escopo para que os dados de evento sejam enviados com sucesso.
"requiredScopes": [
  "timeline"
],
Observe que talvez seja necessário adicionar outros escopos, dependendo dos recursos que seu aplicativo inclui.
Em seguida, no diretório app/ do seu projeto, adicione um diretório app-events. Em app-events/, adicione um arquivo de configuração JSON para definir o tipo de evento de aplicativo. Este arquivo pode ter qualquer nome, mas deve terminar com *-hsmeta.json. Você pode incluir até 750 tipos de eventos por aplicativo, com cada um tendo seu próprio arquivo *-hsmeta.json.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

Configurar o esquema de tipo de evento

No arquivo *-hsmeta.json de tipo de evento, configure seu esquema de tipo de evento. Esse esquema configurará atributos de tipo de evento como nome, modelo de exibição de linha do tempo de registros do CRM e o tipo de objeto do CRM ao qual associar os dados do evento.Embora alguns desses campos possam ser atualizados após a criação, os campos name e objectType não podem ser alterados depois que o tipo de evento é criado.Por exemplo, o esquema de tipo de evento a seguir poderia ser usado para rastrear eventos de login de cliente.
{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo interno para o tipo de evento.
type*StringO tipo de componente. Deve ser app-event.
name*StringO rótulo exibido no HubSpot (até 50 caracteres). Este valor não pode ser atualizado após a criação.
objectType*StringO nome totalmente qualificado do objeto do CRM ao qual as ocorrências de evento podem ser associadas. Este valor não pode ser alterado após a criação. Pode ser um dos seguintes: COMPANY, CONTACT, CUSTOM_OBJECT, DEAL, TICKET, APP_OBJECT.
headerTemplateStringO modelo de renderização para o cabeçalho do cartão de atividades de linha do tempo do CRM. Pode ter até 1.000 caracteres de comprimento.
detailTemplateStringO modelo de renderização para o corpo do cartão de atividades de linha do tempo do CRM. Pode ter até 10.000 caracteres de comprimento.
propertiesMatrizPropriedades definidas para o tipo de evento no qual você armazenará dados de ocorrência de evento. Cada tipo de evento pode ter até 500 propriedades. Saiba mais sobre propriedades, incluindo requisitos e limitações, na documentação de referência de eventos de aplicativo.
3

Carregue as alterações no HubSpot

Carregue seu projeto no HubSpot com o comando hs project upload.
hs project upload
Durante a fase de compilação, o HubSpot validará o tipo de evento. Se houver erros de validação de esquema, a CLI retornará um erro indicando o que corrigir.Por padrão, após uma compilação bem-sucedida, o HubSpot implantará automaticamente o projeto. Se você desativou essa opção nas configurações do projeto, poderá implantar manualmente usando hs project deploy.Após a implantação, seu tipo de evento de aplicativo estará disponível e poderá ser usado para receber dados de ocorrência de eventos.

​
Recuperar fullyQualifiedName

Para enviar dados de ocorrência de eventos para o tipo de evento, você precisará recuperar o fullyQualifiedName através da API de eventos de aplicativo. Esse nome identifica o tipo de evento e precisará ser incluído em todas as operações da API de evento de aplicativo. Para recuperar o eventTypeName, faça uma solicitação POST para https://api.hubapi.com/integrators/timeline/v4/types/projects. No corpo da solicitação, inclua o seguinte:
  • O campo projectName, que deve ser definido como o valor name do arquivo hsproject.json do seu projeto.
  • O campo developerSymbol, que deve ser definido como o valor uid do arquivo de configuração de tipo de evento *-hsmeta.json.
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
A resposta retornará o nome do projeto, o nome do tipo de evento e o fullyQualifiedName. 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
O valor fullyQualifiedName nunca mudará, assim você pode codificá-lo com segurança em sua implementação. A API limita o número de vezes que você pode recuperar esse valor por dia e não pode ser usada programaticamente.

​
Gerenciar tipos de evento

Para atualizar um tipo de evento após a criação, basta atualizar o esquema de tipo de evento em seu projeto e, em seguida, recarregar para compilar e implantar o aplicativo. Se não quiser mais usar um tipo de evento, você poderá excluí-lo do seu projeto. No entanto, antes de excluir um tipo de evento, observe o seguinte:
  • A exclusão de um tipo de evento é uma ação permanente e irreversível.
  • A exclusão de um tipo de evento remove o tipo de evento e todas as ocorrências desse tipo de todas as contas que instalaram o aplicativo.
  • A exclusão de um tipo de evento quebrará outras ferramentas da HubSpot que dependem desse tipo de evento, como relatórios e fluxos de trabalho. Para excluir o tipo de evento, exclua o arquivo de configuração de tipo de evento *-hsmeta.json do seu projeto e, em seguida, carregue e implante o projeto.

​
Migrar um tipo de evento de linha do tempo existente

Se você tiver um aplicativo público existente com um evento de linha do tempo, poderá migrá-lo para a plataforma para desenvolvedores usando a CLI.
Antes de migrar seu aplicativo:
  • Confira o guia de migração de aplicativo público para revisar as considerações e limitações atuais da plataforma para desenvolvedores beta.
  • Depois de migrar um tipo de evento de linha do tempo existente (v1/v3) para a plataforma para desenvolvedores, você terá 7 dias para alterar as solicitações de API de evento de linha do tempo v1/v3 para os novos pontos de extremidade v4, incluindo solicitações de API de ocorrência/instância de evento. Após 7 dias, todas as chamadas existentes para os pontos de extremidade de ocorrência de evento v1/v3 retornarão erros 401.
Para migrar seu aplicativo:
  • No terminal, execute hs app migrate e, em seguida, siga os prompts de terminal para migrar seu aplicativo e evento de linha do tempo.
  • Depois que o processo de migração estiver concluído, seu aplicativo agora estará em um projeto de desenvolvedor, e um diretório de projeto local será criado para você.
  • Para abrir o projeto no HubSpot, navegue para o diretório local do projeto e execute hs project open.
Observe que os arquivos de configuração gerados (*-hsmeta.json) podem conter campos com valores null. Esses campos são um artefato de migração e é seguro removê-los.

​
Próximas etapas

Depois de criar um tipo de evento, saiba como enviar dados de ocorrência de evento via API. Você também pode conferir a documentação de referência de eventos de aplicativo para continuar criando e personalizando seus eventos de aplicativo.