Enviar conclusões de eventos personalizados

Produtos suportados

Requer um dos seguintes produtos ou superior.

Marketing HubEnterprise

Sales HubEnterprise

Service HubEnterprise

Content HubEnterprise

Última modificação: 8 de outubro de 2025

Eventos personalizados são eventos definidos por conta que armazenam detalhes de eventos em propriedades de eventos. Além de personalizar seu código de rastreamento para enviar dados de eventos à HubSpot, você também pode enviar dados de conclusão de eventos por meio desta API. Abaixo, aprenda como usar a API para criar eventos personalizados e enviar/recuperar dados de eventos personalizados.

Definir o evento

Para enviar dados de conclusão de evento para o HubSpot, primeiro você precisa definir o evento, incluindo seus metadados, associações de objetos do CRM e propriedades. Você pode definir eventos usando a API de definição de evento personalizado ou, se você tiver uma assinatura do Marketing Hub Enterprise, poderá criar o evento no HubSpot. Ao criar o evento, a HubSpot fornecerá a opção de incluir um conjunto de propriedades de eventos padrão que você pode usar para armazenar dados de eventos. Você também pode criar propriedades adicionais para o evento. Essas propriedades podem ser criadas ou editadas a qualquer momento. Depois de configurar seu evento, você pode enviar dados para ele por meio da API ou por personalizar seu código de rastreamento da HubSpot.

Enviar dados de evento

Para enviar dados de evento ao HubSpot, faça uma solicitação POST para https://api.hubspot.com/events/v3/send com os dados do evento no corpo da solicitação. Antes de enviar dados de evento, revise os limites abaixo, pois exceder esses limites resultará em erro.

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

Parâmetro	Tipo	Descrição
`eventName`	String	O nome interno do evento. Você pode encontrar isso consultando suas definições de evento existentes ou no aplicativo HubSpot.
`objectId`	String	O ID do registro do CRM com o qual o evento será associado. Para contatos, você pode alternativamente usar o campo `email` ou `utk` para identificar o contato pelo endereço de e-mail ou pelo Token de Usuário da HubSpot. Todos os outros tipos de objetos requerem `objectId`, a menos que um ID correspondente personalizado seja definido para o evento. Se um `customMatchingId` é definido para o evento, a HubSpot definirá ou substituirá automaticamente o `objectId` com base no mapeamento configurado. Saiba mais no guia de definições de eventos personalizados.
`occurredAt`	String	Por padrão, o HubSpot definirá a data/hora de conclusão do evento para a hora em que a solicitação foi enviada. Para especificar a hora de conclusão do evento, inclua um carimbo de data/hora em um campo `occurredAt` no corpo da solicitação `POST` (Formato ISO 8601). Isso pode ser especialmente útil para datar retroativamente dados de eventos para refletir com mais precisão a conclusão de eventos reais.
`properties`	Objeto	As propriedades de evento às quais enviar dados. Isso pode incluir propriedades de evento padrão do HubSpot ou qualquer propriedades personalizadas você definiu para o evento. A maioria das propriedades de evento padrão são propriedades de string, mas você pode revisar todas as propriedades de evento consultando a definição do evento ou navegando até o evento no HubSpot. Se um ID de correspondência personalizado for preparado para o evento, você pode omitir o `objectId`. A HubSpot tentará vincular o evento a um objeto CRM definindo o `objectId` no evento com base no mapeamento configurado. Saiba mais sobre propriedades de evento abaixo.

Observação:

Exceder qualquer um dos limites a seguir resultará em falha na solicitação:

O rótulo da propriedade e o nome interno são limitados a 50 caracteres.
Propriedades de URL e de referência podem ter até 1.024 caracteres, enquanto todas as outras propriedades podem ter até 256 caracteres.
Cada conclusão de evento pode conter dados para até 50 propriedades.
Os nomes internos da propriedade devem começar com uma letra e conter apenas letras minúsculas de a-z, números de 0-9 e sublinhados.
As propriedades com o mesmo nome interno após minúsculas serão consideradas duplicatas e apenas uma delas será usada na conclusão. O HubSpot classificará em ordem lexicográfica ascendente e manterá as últimas propriedades vistas entre as primeiras 50 propriedades.
Há um limite de 500 definições de eventos exclusivos por conta.
Há um limite de 30 milhões de finalizações de eventos por mês.

Recuperar dados de evento

Para recuperar dados de eventos, faça uma GET solicitação para /events/v3/events.

Para retornar todas as conclusões de eventos para um evento específico, inclua o parâmetro eventType junto com o nome do evento interno (por exemplo, pe123456_custom_event). Você pode recuperar todos os tipos de eventos usando a API de análise de eventos.
Para retornar conclusões de eventos para um objeto específico, inclua o parâmetro objectType junto com os parâmetros objectId ou objectProperty.<property>. O objectType deve especificar o tipo de objeto CRM (por exemplo, contact), enquanto os outros parâmetros especificam o valor do identificador exclusivo para o objeto (ID do registro ou um valor de propriedade do identificador exclusivo). Para contatos, você pode usar email como uma propriedade de identificador exclusivo.

Por exemplo, para recuperar todos os eventos concluídos por um contato específico, sua URL de solicitação poderia ser: /events/v3/events?objectType=contact&objectId=111111. Alternativamente, você pode usar o endereço de e-mail do contato: /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com Para filtrar os resultados por conclusões de eventos com um valor de propriedade de evento específico, você pode incluir o parâmetro property.<propertyName>. Por exemplo, para recuperar eventos de visita à página inicial, o URL da solicitação pode ser: /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

Para valores de propriedade com espaços, substitua os espaços por %20 ou +. Por exemplo, property.hs_page_title=home+page.

Saiba mais sobre os parâmetros disponíveis na documentação de referência.

Propriedades do evento

Os dados de conclusão do evento são armazenados nas propriedades do evento, no conjunto de propriedades de eventos padrão ou em propriedades definidas pelo usuário. Ao enviar dados de eventos, inclua um objeto properties com pares chave-valor para as propriedades que você deseja atualizar, juntamente com os valores das propriedades a serem armazenados.

"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }

Os valores que você envia dependerão do tipo de propriedade de evento. A maioria das propriedades de evento padrão é texto de linha única (string). Entretanto, você pode criar propriedades personalizadas de qualquer tipo para cada evento. Revise a tabela abaixo ao formatar os valores de propriedade.

Propriedade Tipo	Descrição
`bool`	Um valor booleano `true` ou `false`.
`enumeration`	Uma string que representa um conjunto de opções. Ao enviar vários valores, separe-os com um ponto e vírgula. No HubSpot, esse tipo corresponde a propriedades de seleção suspensa, botão de opções e várias caixas de seleção.
`date`	Um valor que representa um dia, mês e ano específicos. Os valores devem ser representados na hora UTC e podem ser formatados como Strings ISO 8601 ou carimbos de data/hora EPOCH em milissegundos (ou seja, meia-noite UTC).
`datetime`	Um carimbo de data/hora que representa um dia, mês, ano e hora do dia específicos. Os valores devem ser representados em hora UTC e podem ser formatados como strings de ISO 8601 ou registros de data e hora UNIX em milissegundos.
`number`	Um valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. No HubSpot, este tipo corresponde às propriedades de número e cálculo.
`string`	Uma string de texto simples, com no máximo 65.536 caracteres. No HubSpot, esse tipo corresponde a propriedades de texto de linha única e de várias linhas.

Para exibir as propriedades disponíveis de um evento:

Na sua conta HubSpot, acesse Gestão de Dados > Eventos personalizados.
Na tabela, clique no nome do evento.
Na parte superior, clique na aba Propriedades.
Na tabela de propriedades, veja o tipo sob o nome da propriedade.

Relatórios de atribuição

Eventos JavaScript, como elemento clicado e URL visitada, são preenchidos automaticamente com o tipo de ativo e os dados de interação para os relatórios de atribuição. Para incluir os mesmos dados para eventos rastreados manualmente, você precisará incluir manualmente os dados no corpo da solicitação usando as propriedades do evento. Saiba mais sobre análises de eventos personalizados. Abaixo, conheça os valores disponíveis para tipos de ativos e origens de interação, juntamente com solicitações de exemplo.

Tipo de ativo

Para atribuir um tipo de ativo específico a uma solicitação de evento comportamental personalizado, inclua a propriedade hs_page_content_type no corpo da solicitação. Por exemplo:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Você também pode usar a propriedade hs_asset_type. Se ambos hs_page_content_type e hs_asset_type estiverem incluídos em uma única solicitação, hs_page_content_type substituirá o valor hs_asset_type.

Os tipos de conteúdo padrão do HubSpot, como landing pages e posts de blog, podem ser representados com os seguintes valores:

Valor	Descrição
`STANDARD_PAGE`	Uma interação com uma página do site.
`LANDING_PAGE`	Uma interação com uma landing page.
`BLOG_POST`	Uma interação com uma postagem de blog.
`KNOWLEDGE_ARTICLE`	Uma interação com um artigo da central de conhecimento.

Para todos os outros tipos de ativos, use os seguintes valores:

Valor	Descrição
`AD`	Uma interação com um anúncio, como um anúncio do Facebook ou do Google.
`CALL`	Uma interação com uma chamada.
`CONTACT_IMPORT`	Uma interação através de uma importação de contato.
`CONVERSATION`	Uma interação relacionada a uma conversa HubSpot.
`CUSTOM_BEHAVIORAL_EVENT_NAME`	O nome interno de um evento personalizado, como`pe123456_manually_tracked_event`.
`EMAIL`	Uma interação com um e-mail.
`EXTERNAL_PAGE`	Uma interação com uma página externa.
`INTEGRATIONS`	Uma interação via integração.
`MARKETING_EVENT`	Uma interação com um evento de marketing .
`MEDIA_BRIDGE`	Uma interação via media bridge.
`MEETING`	Uma interação com uma reunião.
`SALES_EMAIL`	Uma interação com um e-mail de vendas individual.
`SEQUENCE`	Uma interação com uma sequência.
`SOCIAL_POST`	Uma interação com um post de mídia social.
`OTHER`	Uma interação com um ativo que não está em uma das categorias acima.

Título de ativo

Para atribuir um evento personalizado a um ativo, inclua a propriedade hs_page_title ou hs_asset_title em sua solicitação com o nome do ativo formatado como uma string. Por exemplo: hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Fontes de interação

Para atribuir um evento comportamental personalizado a uma fonte específica, inclua a propriedade hs_touchpoint_source em sua solicitação com um dos seguintes valores:

Valor	Descrição
`CONVERSATION`	A fonte da interação é uma conversa.
`DIRECT_TRAFFIC`	A fonte da interação é tráfego direto.
`EMAIL_MARKETING`	A fonte da interação é um e-mail de marketing.
`HUBSPOT_CRM`	A fonte da interação é o CRM da HubSpot.
`INTEGRATION`	A fonte da interação é uma integração.
`MARKETING_EVENT`	A fonte da interação é um evento de marketing.
`OFFLINE`	A fonte da interação é offline.
`ORGANIC_SEARCH`	A fonte de interação é a busca orgânica.
`OTHER_CAMPAIGNS`	A fonte da interação é uma campanha não categorizada.
`PAID_SEARCH`	A fonte da interação é um anúncio de pesquisa pago.
`PAID_SOCIAL`	A fonte da interação é um anúncio de redes sociais pago.
`REFERRALS`	A fonte da interação é uma referência.
`SALES`	A fonte da interação é vendas.
`SOCIAL_MEDIA`	A fonte da interação é mídias sociais (não um anúncio de redes sociais pago).

Eventos

Definições de evento

Conclusões de evento

Enviar conclusões de eventos personalizados

Definir o evento

Enviar dados de evento

Observação:

Recuperar dados de evento

Propriedades do evento

Relatórios de atribuição

Tipo de ativo

Título de ativo

Fontes de interação

Eventos

Definições de evento

Conclusões de evento

​Definir o evento

​Enviar dados de evento

​Observação:

​Recuperar dados de evento

​Propriedades do evento

​Relatórios de atribuição

​Tipo de ativo

​Título de ativo

​Fontes de interação

Definir o evento

Enviar dados de evento

Observação:

Recuperar dados de evento

Propriedades do evento

Relatórios de atribuição

Tipo de ativo

Título de ativo

Fontes de interação