> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rovax.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Hotmart
> Eventos Hotmart consumidos pela Timely.ai — compras, cancelamentos e assinaturas para automações de cobrança e acesso
A **Hotmart** é uma plataforma de venda de produtos digitais amplamente usada no Brasil. A Timely.ai permite que você integre eventos da Hotmart com seus agentes de IA — por exemplo, liberar acesso automático a um grupo, enviar mensagem de boas-vindas via WhatsApp ou atualizar um contato no CRM toda vez que uma compra for aprovada.
A integração funciona em dois modelos:
1. **Webhook direto**: a Hotmart envia eventos para um endpoint da Timely (ou seu próprio servidor), que aciona automações no workspace.
2. **Integração nativa**: configure a URL de webhook gerada pelo seu agente Timely diretamente no painel da Hotmart.
## Configurar a URL de webhook na Hotmart
Vá para **Ferramentas → Webhooks** na conta da Hotmart (produtor ou coprodutor).
Clique em **Adicionar webhook** e informe a URL. Para enviar eventos para um agente Timely, use o endpoint gerado em **Configurações → Canais → Webhook de entrada** do seu workspace.
Selecione `PURCHASE_COMPLETE`, `PURCHASE_CANCELED`, `PURCHASE_REFUNDED`, `SUBSCRIPTION_CANCELLATION` e outros conforme sua necessidade.
Use o botão **Testar** da Hotmart para enviar um payload de exemplo ao seu endpoint.
## Validação da assinatura Hotmart
A Hotmart envia o header `X-Hotmart-Webhook-Token` com um token fixo configurado por você no painel. Não é HMAC — é uma comparação direta de token. Por isso, certifique-se de usar HTTPS e de manter o token em segredo.
```typescript Node.js theme={null}
const HOTMART_TOKEN = process.env.HOTMART_WEBHOOK_TOKEN!;
app.post("/webhook/hotmart", (req, res) => {
const token = req.headers["x-hotmart-webhook-token"];
if (token !== HOTMART_TOKEN) {
return res.status(401).json({ error: "Invalid token" });
}
// processa o evento...
res.sendStatus(200);
});
```
Como a Hotmart não usa HMAC, qualquer servidor com o token pode forjar uma requisição. Use o token apenas em HTTPS, nunca em HTTP, e nunca exponha o token em logs.
## Evento: PURCHASE\_COMPLETE
Disparado quando uma compra é aprovada (cartão, boleto compensado, PIX confirmado).
```json theme={null}
{
"id": "HP-1234567890",
"creation_date": 1713456789000,
"event": "PURCHASE_COMPLETE",
"version": "2.0.0",
"data": {
"product": {
"id": 123456,
"name": "Curso de Automação com IA",
"ucode": "PRODUTO_UCODE"
},
"purchase": {
"approved_date": 1713456789000,
"full_price": {
"value": 297.0,
"currency_value": "BRL"
},
"order_date": 1713456700000,
"status": "APPROVED",
"transaction": "HP-1234567890",
"payment": {
"type": "CREDIT_CARD",
"installments_number": 3
},
"offer": {
"code": "OFERTA_BASICA",
"payment_mode": "PAYMENT"
}
},
"buyer": {
"name": "Maria Oliveira",
"email": "maria@exemplo.com.br",
"phone": "+5511988887777",
"document": "***.***.***-**"
},
"subscription": null,
"commissions": []
}
}
```
## Evento: PURCHASE\_CANCELED
Disparado quando uma compra é cancelada antes da compensação (boleto vencido, cartão recusado definitivamente).
```json theme={null}
{
"id": "HP-1234567891",
"creation_date": 1713543200000,
"event": "PURCHASE_CANCELED",
"version": "2.0.0",
"data": {
"product": {
"id": 123456,
"name": "Curso de Automação com IA",
"ucode": "PRODUTO_UCODE"
},
"purchase": {
"status": "CANCELED",
"transaction": "HP-1234567891",
"cancellation_date": 1713543200000,
"payment": {
"type": "BOLETO",
"installments_number": 1
}
},
"buyer": {
"name": "Carlos Mendes",
"email": "carlos@exemplo.com.br",
"phone": "+5511977776666",
"document": "***.***.***-**"
}
}
}
```
## Evento: PURCHASE\_REFUNDED
Disparado quando um reembolso é aprovado após a compra já ter sido completada.
```json theme={null}
{
"id": "HP-1234567892",
"creation_date": 1713629800000,
"event": "PURCHASE_REFUNDED",
"version": "2.0.0",
"data": {
"product": {
"id": 123456,
"name": "Curso de Automação com IA",
"ucode": "PRODUTO_UCODE"
},
"purchase": {
"status": "REFUNDED",
"transaction": "HP-1234567890",
"full_price": {
"value": 297.0,
"currency_value": "BRL"
}
},
"buyer": {
"name": "Maria Oliveira",
"email": "maria@exemplo.com.br",
"phone": "+5511988887777"
}
}
}
```
## Evento: SUBSCRIPTION\_CANCELLATION
Disparado quando uma assinatura recorrente é cancelada (pelo comprador ou pelo produtor).
```json theme={null}
{
"id": "HP-1234567893",
"creation_date": 1713716200000,
"event": "SUBSCRIPTION_CANCELLATION",
"version": "2.0.0",
"data": {
"product": {
"id": 123456,
"name": "Mentoria Mensal IA",
"ucode": "PRODUTO_UCODE"
},
"purchase": {
"status": "CANCELLED_BY_CUSTOMER",
"transaction": "HP-1234567893",
"subscription_anticipation_purchase": false
},
"subscription": {
"subscriber_code": "SUB-ABC12345",
"status": "CANCELLED",
"plan": {
"name": "Plano Mensal",
"recurrency_period": 30
},
"date_next_charge": null
},
"buyer": {
"name": "Pedro Ramos",
"email": "pedro@exemplo.com.br",
"phone": "+5511966665555"
}
}
}
```
## Outros eventos disponíveis
| Evento | Quando ocorre |
| --------------------------- | ---------------------------- |
| `PURCHASE_COMPLETE` | Compra aprovada |
| `PURCHASE_CANCELED` | Compra cancelada |
| `PURCHASE_REFUNDED` | Reembolso aprovado |
| `PURCHASE_CHARGEBACK` | Chargeback registrado |
| `PURCHASE_PROTEST` | Disputa aberta |
| `PURCHASE_DELAYED` | Pagamento atrasado (boleto) |
| `PURCHASE_EXPIRED` | Boleto vencido sem pagamento |
| `SUBSCRIPTION_CANCELLATION` | Assinatura cancelada |
| `SWITCH_PLAN` | Comprador mudou de plano |
## Campos principais do payload
| Campo | Tipo | Descrição |
| ----------------------------------- | ------ | ----------------------------------- |
| `id` | string | ID único do evento Hotmart (`HP-*`) |
| `event` | string | Tipo do evento |
| `creation_date` | number | Timestamp em milissegundos |
| `data.product.id` | number | ID do produto na Hotmart |
| `data.purchase.transaction` | string | Código de transação único |
| `data.purchase.status` | string | Status da compra |
| `data.buyer.email` | string | Email do comprador |
| `data.buyer.phone` | string | Telefone (formato internacional) |
| `data.subscription.subscriber_code` | string | Código único do assinante |
## Automações comuns com Hotmart
Ao receber `PURCHASE_COMPLETE`, dispare uma mensagem automática pelo agente Timely usando o `phone` do comprador.
Ao receber `SUBSCRIPTION_CANCELLATION`, remova o contato de grupos ou marque como inativo no CRM da Timely.
Ao receber `PURCHASE_EXPIRED`, inicie um fluxo de recuperação com mensagem e novo link de pagamento.
Sincronize dados do comprador como contato na Timely usando a API de Contacts.
## Próximos passos
Crie e atualize contatos programaticamente ao receber eventos da Hotmart.
Configure endpoints para receber eventos do seu workspace Timely.