> For the complete documentation index, see [llms.txt](https://help.curseduca.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.curseduca.com/integracoes/hubspot-1.md).

# Hubspot

## Guia de Integração: Waid e HubSpot (Eventos)

Bem-vindo ao guia de integração entre a plataforma Waid e o HubSpot! Este documento foi criado para ajudar você e sua equipe a entenderem como a nossa plataforma se comunica com o seu HubSpot, enviando informações valiosas sobre a jornada dos seus alunos.Aqui, explicamos de forma simples o que acontece nos bastidores e, principalmente, o que você precisa configurar no seu HubSpot para que a mágica aconteça.

### 1. Como funciona essa integração?

Sempre que um aluno realiza uma ação importante dentro da Waid, como se matricular em um curso, assistir a uma aula ou conquistar um certificado, nós enviamos um aviso automático para o seu HubSpot.

No HubSpot, esse aviso é registrado como um Evento Comportamental Personalizado **(Custom Behavioral Event)**, vinculado diretamente ao contato do aluno pelo e-mail dele.\
O que você ganha com isso?

Com esses eventos chegando no seu HubSpot, sua equipe pode:

* Criar listas dinâmicas — ex.: "alunos que concluíram o curso X".
* Montar automações (Workflows) — ex.: enviar um e-mail de parabéns quando o aluno tirar o certificado.
* Gerar relatórios — ex.: número de matrículas por mês.
* Visualizar a Timeline do contato — toda a jornada do aluno em ordem cronológica.

{% hint style="danger" %}
***Atenção:** Essa integração funciona em mão única da Waid para o HubSpot. Não importamos contatos nem alteramos dados cadastrais; apenas registramos os eventos da jornada educacional.*
{% endhint %}

### 2. Quais eventos a Waid envia para o HubSpot?

Atualmente, enviamos 7 eventos principais. Cada um se tornará um evento separado no seu HubSpot.

| O que acontece na Waid  | Quando é enviado                                         | O que chega no HubSpot                            |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------------- |
| Matrícula realizada     | O aluno é matriculado em um curso ou conteúdo.           | Nome e ID do conteúdo + progresso 0%              |
| Primeira aula concluída | O aluno termina a primeira aula (progresso sai do zero). | Nome e ID do conteúdo + progresso 1%              |
| 25% do curso concluído  | O aluno atinge 25% de progresso.                         | Nome e ID do conteúdo + progresso 25%             |
| 50% do curso concluído  | O aluno atinge a metade do curso.                        | Nome e ID do conteúdo + progresso 50%             |
| 75% do curso concluído  | O aluno atinge 75% de progresso.                         | Nome e ID do conteúdo + progresso 75%             |
| Curso finalizado (100%) | O aluno conclui todas as aulas.                          | Nome e ID do conteúdo + progresso 100%            |
| Certificado conquistado | O sistema emite o certificado para o aluno.              | Nome e ID do conteúdo + certificado emitido = sim |

{% hint style="info" %}
*Eventos como pagamentos, login na plataforma ou interações em grupos não são enviados por esta integração no momento.*
{% endhint %}

### 3. Como o HubSpot reconhece o aluno?

A chave de ligação entre a Waid e o HubSpot é o e-mail do aluno.

* Se o aluno já existir no HubSpot com aquele e-mail, o evento é adicionado à linha do tempo dele.
* Se o aluno ainda não existir, o HubSpot cria um novo contato automaticamente, usando apenas o e-mail.

{% hint style="success" %}
***Dica:** Para evitar contatos duplicados, oriente seus alunos a usarem o mesmo e-mail tanto nas comunicações com sua empresa quanto no login da plataforma Waid.*
{% endhint %}

### 4. O que você precisa configurar no HubSpot

Para que os eventos comecem a chegar, sua equipe precisa realizar algumas configurações dentro da sua conta do HubSpot. Siga o passo a passo abaixo.

#### Passo 1: Criar um Aplicativo Privado e gerar o Token

Precisamos de uma chave de acesso segura para enviar os dados.1.

1. No HubSpot, acesse Configurações → Integrações → Private Apps.
2. Clique em Create a private app.
3. Dê um nome como "Integração Waid".
4. Na aba Scopes, marque as três permissões baixo:\
   • `crm.objects.contacts.read`\
   • `crm.objects.contacts.write`\
   • `behavioral_events.event_send5`
5. Clique em Create app e copie o Access token gerado.
6. Envie esse token para a equipe da Waid, nós o cadastraremos no sistema.

{% hint style="warning" %}
*Esse token funciona como uma senha. Envie-o de forma segura e evite compartilhá-lo em locais públicos.*
{% endhint %}

#### Passo 2: Criar os Eventos Personalizados no HubSpot

Agora você precisa preparar o HubSpot para receber cada um dos 7 eventos.

1. Acesse Configurações *→ Data Management → Custom Events. (Em alguns planos, pode estar em Reports → Custom Behavioral Events.)*
2. Clique em Create event.
3. Dê um nome interno claro, como `Waid_matricula_criada` ou `Waid_curso_concluido`.
4. Adicione as propriedades que o evento vai receber, conforme a tabela abaixo:

| Evento                  | Propriedades a criar                                                          |
| ----------------------- | ----------------------------------------------------------------------------- |
| Matrícula realizada     | content\_id (número), content\_title (texto), progress (texto)                |
| Primeira aula concluída | content\_id (número), content\_title (texto), progress (texto)                |
| 25% do curso concluído  | content\_id (número), content\_title (texto), progress (texto)                |
| 50% do curso concluído  | content\_id (número), content\_title (texto), progress (texto)                |
| 75% do curso concluído  | content\_id (número), content\_title (texto), progress (texto)                |
| Curso finalizado (100%) | content\_id (número), content\_title (texto), progress (texto)                |
| Certificado conquistado | content\_id (número), content\_title (texto), certificate\_emitted (booleano) |

{% hint style="info" %}
Se uma propriedade não for criada no HubSpot, a informação enviada pela Waid será descartada. O evento aparece, mas sem os detalhes.
{% endhint %}

{% hint style="info" icon="floppy-disk" %}
Salve o evento e anote o "internal name" gerado pelo HubSpot, geralmente no formato `pe<numero>_<nome>`
{% endhint %}

#### Passo 3: Enviar os Nomes Internos para a Waid

Com os eventos criados, envie para a equipe da Waid uma lista simples com:

* O internal name de cada evento criado no HubSpot.
* A qual evento da Waid ele corresponde (ex.: "pe12345\_waid\_matricula → Matrícula Realizada").

{% hint style="info" %}
*Sem essa lista, a Waid não saberá para qual evento enviar cada informação mesmo com o token configurado, nada será enviado.*
{% endhint %}

#### Passo 4: Ativação pela Waid

Assim que recebermos o token **(Passo 1)** e a lista de internal names **(Passo 3)**, nossa equipe ativará a integração. A partir desse momento, os eventos começarão a chegar no seu HubSpot.

### 5. Resumo: quem faz o quê?

| O que precisa ser feito                          | Responsável |
| ------------------------------------------------ | ----------- |
| Detectar o progresso do aluno na plataforma      | Waid        |
| Enviar os eventos para o HubSpot                 | Waid        |
| Criar o Private App e gerar o Token              | Cliente     |
| Criar os Custom Events e suas propriedades       | Cliente     |
| Enviar o Token e os internal names para a Waid   | Cliente     |
| Configurar o de-para no sistema                  | Waid        |
| Ativar a integração                              | Waid        |
| Criar automações, listas e relatórios no HubSpot | Cliente     |

### 6. Como testar se está funcionando?

Após a Waid confirmar a ativação:

1. Matricule um aluno de teste em um curso na plataforma Waid.
2. Aguarde alguns minutos (o envio é assíncrono).
3. Abra o HubSpot e busque o contato com o e-mail desse aluno.
4. Verifique a Timeline do contato — o evento de matrícula deve aparecer com todos os detalhes.
5. Opcionalmente, crie uma Lista Dinâmica filtrando pelo evento e confirme que o aluno aparece nela.

Evento não apareceu após 10 minutos? Verifique:

* O e-mail do aluno na Waid é idêntico ao e-mail no HubSpot?
* O token foi gerado corretamente e não foi revogado?
* Os internal names foram enviados para a Waid?
* A Waid confirmou que a integração foi ativada?

Se tudo estiver correto e o problema persistir, abra um chamado de suporte informando o e-mail do aluno testado e o horário do teste.

### 7. Pontos de atenção

* Plano necessário: O recurso de Custom Behavioral Events está disponível apenas no plano Marketing Hub Enterprise do HubSpot. Confirme seu plano antes de iniciar.
* Apenas 7 eventos: Pagamentos, login e outras ações não fazem parte desta integração.
* Sem retroatividade: Somente eventos ocorridos após a ativação são registrados — o histórico anterior não é enviado.
* Mão única: Alterações feitas no HubSpot não refletem na plataforma Waid.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.curseduca.com/integracoes/hubspot-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.