Cenário
Cliente compra “Curso Premium” na Hotmart. Em segundos, ele recebe acesso ao grupo “Alunos Premium” e ao curso na sua comunidade Cativa. A ponte entre os dois lados é o conceito de badge como permissão: o badgePremium é configurado no Console como requisito de acesso ao grupo e ao curso. Quando o usuário ganha o badge, o acesso aparece automaticamente. Quando perde, some.
Pré-requisitos
- API Key da Cativa — gerada no Console (Developers > API Keys). Veja Quick Start: API Key.
- Badge configurado no Console — crie o badge
Premium(ou o nome do seu produto) e configure-o como requisito de acesso no grupo/curso correspondente. Veja Badges como permissão. - Webhook de compra do seu gateway — Hotmart, Kiwify, Eduzz e Stripe disparam webhook pra um endpoint do seu servidor quando uma compra é confirmada. Não aponte o webhook do gateway diretamente pra Cativa — você precisa de um servidor proxy que recebe, valida e traduz o evento.
- Email confiável do comprador — todos os gateways enviam o email no payload da compra. Esse é o ponto-de-junção com o usuário Cativa.
Arquitetura do fluxo
- Validar o webhook do gateway (cada um tem assinatura própria — confira a doc do gateway).
- Tratar idempotência (Hotmart pode disparar o mesmo webhook duas vezes).
- Logar o purchase ID do gateway pra auditoria/conciliação.
- Decidir o badge correto baseado em qual produto foi comprado.
user_received_badge pra disparar email de boas-vindas, atualizar CRM, ou registrar evento no analytics.
Implementação
Receber o webhook do gateway
Cada gateway tem seu próprio formato de webhook e seu próprio mecanismo de assinatura. Configure o webhook no painel do gateway apontando pra um endpoint do seu servidor (ex:
https://meuapp.com/webhooks/hotmart).A Cativa não documenta o formato do webhook desses gateways — consulte a doc oficial:Esqueleto do receiver (Express, exemplo Hotmart):Identificar o usuário na Cativa pelo email
Hoje há duas situações:Caso A — o comprador já tem conta na Cativa: você precisa achar o Caso B — o comprador ainda não tem conta na Cativa: você precisa fazer ele se cadastrar primeiro.
User.Id dele.O endpoint público para parceiros buscarem usuário arbitrário pelo email está em desenvolvimento. Hoje, esse lookup usa um endpoint admin que não está disponível para API Keys de parceiro.Workaround recomendado: mantenha uma tabela local
email → cativa_user_id populada pelo webhook user_created da Cativa. Toda vez que alguém entra na comunidade, você grava a linha. Quando a compra chegar, faz lookup local sem bater na API.Criação de usuário direto via API Key de parceiro está em desenvolvimento. Workaround atual: envie um email com o link de cadastro do tenant + um lembrete de que o badge será atribuído assim que ele entrar. Quando ele se cadastrar, o webhook
user_created chega no seu servidor e você completa o fluxo (ver step 4).Atribuir o badge
Mapeie o Esquema mental do que vai parecer:A Cativa garante que atribuir o mesmo badge duas vezes é idempotente (ver Badges como permissão) — então retries causados por timeout ou re-disparo do gateway não criam efeito duplicado.
productId do gateway pro badgeId da Cativa configurado no Console.A atribuição de badge via API Key de parceiro está em desenvolvimento. Hoje, atribuição/remoção de badges é feita no Console (manualmente ou via importação) ou via fluxos automáticos da plataforma. Quando o endpoint público estiver disponível, esta página será atualizada com o cURL completo. Pra liberar o seu caso enquanto isso, abra ticket em dev@cativa.digital.
(Opcional) Reagir ao webhook user_received_badge
A Cativa dispara o webhook
user_received_badge toda vez que um badge é atribuído (não importa se foi via API, Console, ou outro fluxo). Cadastre um listener para ele se você quer:- Mandar email de boas-vindas com link pra comunidade
- Atualizar o status do contato no CRM
- Registrar conversão no analytics
Cancelamento e chargeback
Quando o gateway cancela ou faz chargeback, você quer remover o badge pra revogar o acesso.A remoção de badge via API Key de parceiro está no mesmo waitlist da atribuição. Mesmo workaround: hoje é feito no Console; o endpoint público sai em breve.
Erros comuns
Comprador não tem cadastro Cativa, ficou com a compra paga e sem acesso
Comprador não tem cadastro Cativa, ficou com a compra paga e sem acesso
Esse é o caso mais comum. O cliente comprou na Hotmart antes de entrar na sua comunidade.Solução: o step 2 acima cobre — registre a intenção em
pendingGrants e dispare o convite. Subscreva o webhook user_created e, quando o cadastro acontecer, complete a atribuição:Email diferente entre o gateway e a Cativa do mesmo usuário
Email diferente entre o gateway e a Cativa do mesmo usuário
Acontece quando o cliente compra com email pessoal e entra na comunidade com email corporativo. Não tem solução automática.Solução: ofereça uma página “Já comprei, mas estou logado com outro email” no seu app, onde o cliente informa o email da compra. Você valida o purchase ID localmente e atribui o badge pro usuário logado (não pro email da compra).
Webhook do gateway disparou duas vezes — usuário ganhou o badge duas vezes?
Webhook do gateway disparou duas vezes — usuário ganhou o badge duas vezes?
A atribuição de badge na Cativa é idempotente: aplicar o mesmo badge duas vezes resulta no mesmo estado final. Mas por garantia, salve o Isso também ajuda a auditar/conciliar mais tarde (ex: relatório financeiro vs concessões).
purchaseId do gateway numa tabela local e cheque antes:Gateway oferece "assinatura recorrente" — como tratar renovação mensal?
Gateway oferece "assinatura recorrente" — como tratar renovação mensal?
Cada gateway dispara webhook quando a renovação é cobrada com sucesso (ex: Hotmart
SUBSCRIPTION_CHARGE_SUCCESS). Trate como um handlePurchase idempotente — re-aplica o badge (sem efeito se já está). Se a renovação falha (ex: cartão recusado), trate como handleCancellation.Cliente reembolsou em < 7 dias mas continuou usando a comunidade
Cliente reembolsou em < 7 dias mas continuou usando a comunidade
Você precisa reagir ao chargeback rapidamente — o webhook do gateway chega, você remove o badge na hora, acesso aos recursos atrelados some. Não confie em job batch noturno pra isso.
Múltiplos badges para um mesmo produto (curso + bônus)
Múltiplos badges para um mesmo produto (curso + bônus)
Mapeie um produto pra vários badges se necessário. Exemplo: produto
Curso Premium libera tanto Premium (acesso ao curso) quanto Mentoria-2026 (acesso ao grupo de mentoria). Faça duas atribuições no handlePurchase.Próximos passos
Webhooks da Cativa
Cadastre listeners para
user_created (cobrir caso “comprou antes de cadastrar”) e user_received_badge (disparar ações pós-acesso).Sincronizar membros do CRM
Se você também usa CRM, combine este fluxo com sincronização de tags pra ter um único hub de permissões.
