Última modificação: 11 de setembro de 2025
Veja abaixo as informações de referência para usar eventos de aplicativo, incluindo esquemas de tipo de evento, modelos de renderização de linha do tempo de eventos, campos de ocorrência de eventos e muito mais.

​
Estrutura do projeto

No contexto de um projeto, as definições de tipo de evento serão colocadas em um diretório app-events em app/. O diretório app-events deve conter um arquivo de definição de esquema JSON para cada tipo de evento (*-hsmeta.json). 
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
Para incluir definições de tipo de evento em um projeto, é necessário o seguinte:
  • Seu aplicativo deve usar a autenticação OAuth e ser configurado para distribuição no Marketplace de aplicativos. Além disso, o aplicativo deve incluir timeline no seu requiredScopes. Saiba mais sobre a configuração de aplicativos.
  • Seu projeto deve ser implantado com êxito para que um componente de evento de aplicativo possa ser incluído.

​
Esquema de tipo de evento

Veja abaixo as opções de configuração disponíveis para esquemas de tipo de evento (*-hsmeta.json). Observe que alguns atributos abaixo não podem ser alterados depois da criação do tipo de evento.
Cada aplicativo tem um limite de 750 tipos de eventos.
{
 "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 de evento abaixo.

​
Propriedades do evento

Ao definir o esquema de evento, use a matriz properties para definir os campos para os quais os dados de ocorrência de evento serão enviados. Cada tipo de evento pode ter até 500 propriedades. 
 "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
name*StringO nome interno da propriedade. Deve ter entre 1 e 500 caracteres minúsculos. Os nomes das propriedades devem ser exclusivos por tipo de evento. Este valor não pode corresponder ao regex "[A-Za-z0-9_\\-.]+" ou começar com hs_.
label*StringO rótulo exibido em HubSpot. Deve ter entre 1 e 500 caracteres minúsculos.
type*StringO tipo de dados capturados na propriedade. Pode ser: STRING, NUMBER, DATE, ENUMERATION.
optionsMatrizPara tipos de propriedade ENUMERATION, este campo fornece as opções disponíveis. Deve conter pelo menos uma opção. Cada opção é um objeto que contém:
  • name: o rótulo para a opção exibida em HubSpot.
  • value: o valor interno fornecido pela ocorrência do evento.
name e label devem ser exclusivos ao tipo de evento.
objectPropertyNameStringSe incluído, o nome do objeto do CRM que deve ser atualizado quando dados de evento são enviados ao HubSpot. O valor desta propriedade substituirá os valores existentes nessa propriedade. Saiba mais sobre como usar o carimbo de propriedades de registro de CRM abaixo.

​
Carimbos de propriedade

Em alguns casos, talvez você queira modificar os valores da propriedade do registro do CRM com base nos dados de ocorrência do evento do aplicativo. Por exemplo, você pode querer atualizar o nome e o sobrenome de um contato com novos valores definidos pela ocorrência (por exemplo, envio de formulário). Para atualizar as propriedades de registro por meio de ocorrências de evento, você pode vincular uma propriedade de evento a uma propriedade de CRM no esquema de tipo de evento. Nos campos de definição de uma determinada propriedade de evento, inclua o campo objectPropertyName e especifique a propriedade de CRM a vincular. Quando uma propriedade é vinculada, o HubSpot sempre atualiza o valor da propriedade no registro de CRM usando o valor da ocorrência mais recente com base no campo timestamp. Por exemplo, o esquema de tipo de evento abaixo vincula a propriedade de evento customerName a uma propriedade do contato personalizada denominada custom_property_name. Quando os dados de ocorrência de evento incluir um valor para customerName, custom_property_name será atualizado para o registro de CRM associado. 
 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

​
Renderização de modelos

Os esquemas de tipo de evento podem incluir o headerTemplate e detailTemplate para configurar como as ocorrências do evento são renderizadas nas linhas do tempo de registro de CRM.
  • headerTemplate: uma descrição em uma linha do evento na parte superior do cartão de atividade (até 1.000 caracteres).
  • detailTemplate: os detalhes do evento no corpo do cartão de atividade (até 10.000 caracteres).
Os modelos de renderização são gravados usando Marcações com modelos de Handlebars. Esses modelos podem processar dados de ocorrência do evento da seguinte maneira:
  • Em ambos os modelos, você pode acessar qualquer dados de property passados pela ocorrência do evento usando a sintaxe {{propertyName}}.
  • Na janela detailTemplate, você pode acessar também valores de extraData transmitidos pela ocorrência do evento usando a sintaxe {{extraData.fieldName}}. Você pode acessar qualquer categoria de atributo em extraData por meio da notação de ponto, como {{extraData.person1.preferredName}}.
O objeto extraData só pode conter JSON válido. Se o JSON estiver malformado, a ocorrência será rejeitada e você receberá uma resposta de erro.
Por exemplo, os modelos abaixo usam os dados de propriedade customerName e loginLocation com o campo surveyData de extraData enviado através da ocorrência do evento. Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato. 
"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
Como os modelos são criados com marcações e handlebars, você pode aproveitar os auxiliares de handlebars para tornar o conteúdo mais dinâmico. Por exemplo, o seguinte detailTemplate inclui o #if auxiliar para processar conteúdo condicionalmente com base no fato de os dados de ocorrência do evento incluírem o campo surveyData em extraData.
  • Se extraData contém surveyData, as respostas da pesquisa pós-login são mostradas.
  • Se não havia surveyData presente na ocorrência do evento, renderizar No additional information..
Captura de tela que mostra o que o código de exemplo abaixo renderizaria como na linha do tempo de contato. 
"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

​
Uso de iframes

Quando os dados de ocorrência do evento contiverem o campo timelineIFrame, o cartão de atividade da linha do tempo incluirá um hiperlink em que os usuários podem clicar para abrir o conteúdo vinculado em um iframe. Captura de tela de um link incluído em um cartão de atividade de linha do tempo devido ao campo timelineIFrame 
"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }
CampoTipoDescrição
linkLabelStringO texto do hiperlink que iniciará o iframe ao ser clicado.
headerLabelStringO rótulo da janela do modal que mostra o conteúdo do iframe.
urlStringO URL do conteúdo do iframe.
widthInteiroA largura do modal iframe.
heightInteiroA altura do modal iframe.

​
Ocorrências de eventos

Para enviar ocorrências de um determinado tipo de evento, faça uma solicitação de POST aos pontos de extremidade abaixo. A API de eventos do aplicativo inclui pontos de extremidade para enviar ocorrências de eventos únicos e lotes de várias ocorrências de eventos. Para ambos os pontos de extremidade, os dados de ocorrência do evento precisarão ser validados em relação a um esquema de tipo de evento existente, que você especificará com eventTypeName no corpo do pedido.
Para enviar uma única ocorrência de evento, faça uma solicitação de POST para /integrators/timeline/v4/events.No corpo da solicitação, inclua os dados de ocorrência do evento, cumprindo o esquema definido do tipo de evento.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},
No corpo da solicitação, inclua dados com base no esquema de tipo de evento definido. O corpo da solicitação deve incluir eventTypeName, que você pode recuperar via API. 
  {
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer":"Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer":"Extremely likely"
      }
    ]
  }
}

Campos marcados com * são obrigatórios.

CampoTipoDescrição
eventTypeName*StringO nome totalmente qualificado do tipo de evento, usado para identificar o evento via API. Esse valor é automaticamente definido pelo HubSpot e pode ser obtido através da API depois da criação do tipo de evento. Este valor não pode ser alterado após a criação.
objectId*StringO ID do registro de CRM para associar à ocorrência do evento. Este campo pode ser usado para todos os tipos de registros de CRM e é o identificador recomendado. Saiba mais sobre associação de registro de CRM.
emailStringPara associações de contato, você pode fornecer o endereço de e-mail do contato a ser associado. Saiba mais sobre associação de registro de CRM.
utkStringPara associações de contato, você pode fornecer o token de usuário de um contato existente para associar. Saiba mais sobre associação de registro de CRM.
domainStringPara associações de empresa, você pode fornecer o domínio do site de uma empresa existente. Saiba mais sobre associação de registro de CRM.
timestampStringDefine a hora da ocorrência do evento (formato ISO 8601). Se não for fornecida, o HubSpot usará como padrão o carimbo de data/hora do envio de dados de ocorrência de evento.
propertiesObjetoPares chave-valor de nomes de propriedades e valores de propriedades que você definiu para o tipo de evento.
extraDataMatrizQuando incluída, fornece informações adicionais para renderização de linhas do tempo. Deve ser um JSON válido. Saiba mais sobre dados extras em modelos de renderização.
timelineIFrameObjetoQuando incluído, o cartão de linha do tempo conterá um hiperlink que permite que os usuários abram o conteúdo vinculado em um iframe. Saiba mais sobre como usar iframes.
idStringUm identificador exclusivo para a ocorrência do evento. Deve ser exclusivo dentro do tipo de evento. Se não for fornecido, o HubSpot gerará um UUID aleatório. Quando houver vários eventos com o mesmo ID, o primeiro será aceito e todos os outros serão rejeitados.
Mesmo que alguma ocorrência não seja validada, as ocorrências validadas serão aceitas e mantidas. A mensagem de erro na resposta fornecerá informações sobre o que precisa ser corrigido. Captura de tela de um exemplo de mensagem de erro que você pode receber ao enviar dados de ocorrência de evento

​
Associação de registro de CRM

Cada ocorrência de evento deve ser associada a um registro de CRM, com o tipo de objeto de CRM definido pelo esquema de tipo de evento. A API de eventos de aplicativo inclui vários campos para associar dados de ocorrência de evento com registros de CRM. Para todos os objetos de CRM compatíveis, recomendamos usar o campo objectId. No entanto, há algumas situações em que outros campos devem ser usados.
  • utk/email: se você não souber o ID do contato, use o campo utk e/ou email para identificação. Fornecer esses dois identificadores também permite criar e atualizar contatos. Por exemplo:
    • Se utk corresponde a um contato existente, mas email não corresponde, o HubSpot atualizará o contato com o novo endereço de e-mail.
    • Se nenhum objectId for fornecido, a ocorrência do evento será associada a um contato existente que corresponda ao utk/email, ou HubSpot criará um contato se nenhuma correspondência for encontrada.
    • Observe que o utk sozinho não pode criar novos contatos. Você deve sempre incluir email com utk para que associação seja adequada.
  • domain: para associações de empresa, você deve fornecer o objectId, mas você também pode incluir domain para atualizar a propriedade de domain daquela empresa.