Hotmart - Timely.ai

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:

Webhook direto: a Hotmart envia eventos para um endpoint da Timely (ou seu próprio servidor), que aciona automações no workspace.
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

Acesse o painel da Hotmart

Vá para Ferramentas → Webhooks na conta da Hotmart (produtor ou coprodutor).

Adicione um novo webhook

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 os eventos

Selecione PURCHASE_COMPLETE, PURCHASE_CANCELED, PURCHASE_REFUNDED, SUBSCRIPTION_CANCELLATION e outros conforme sua necessidade.

Salve e teste

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.

Node.js

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).

{
  "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).

{
  "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.

{
  "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).

{
  "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

Boas-vindas via WhatsApp

Ao receber PURCHASE_COMPLETE, dispare uma mensagem automática pelo agente Timely usando o phone do comprador.

Revogar acesso

Ao receber SUBSCRIPTION_CANCELLATION, remova o contato de grupos ou marque como inativo no CRM da Timely.

Recuperação de boleto

Ao receber PURCHASE_EXPIRED, inicie um fluxo de recuperação com mensagem e novo link de pagamento.

Atualização de CRM

Sincronize dados do comprador como contato na Timely usando a API de Contacts.

Próximos passos

Contacts — API Reference

Crie e atualize contatos programaticamente ao receber eventos da Hotmart.

Webhooks — API Reference

Configure endpoints para receber eventos do seu workspace Timely.

​Configurar a URL de webhook na Hotmart

​Validação da assinatura Hotmart

​Evento: PURCHASE_COMPLETE

​Evento: PURCHASE_CANCELED

​Evento: PURCHASE_REFUNDED

​Evento: SUBSCRIPTION_CANCELLATION

​Outros eventos disponíveis

​Campos principais do payload

​Automações comuns com Hotmart

Boas-vindas via WhatsApp

Revogar acesso

Recuperação de boleto

Atualização de CRM

​Próximos passos

Contacts — API Reference

Webhooks — API Reference

Configurar a URL de webhook na Hotmart

Validação da assinatura Hotmart

Evento: PURCHASE_COMPLETE

Evento: PURCHASE_CANCELED

Evento: PURCHASE_REFUNDED

Evento: SUBSCRIPTION_CANCELLATION

Outros eventos disponíveis

Campos principais do payload

Automações comuns com Hotmart

Próximos passos