Skip to main content
Você vende um curso ou produto digital num gateway externo (Hotmart, Kiwify, Eduzz, Stripe Checkout) e quer que a compra automaticamente libere acesso a um grupo, curso ou espaço dentro da sua comunidade Cativa. Este guia mostra a arquitetura recomendada e os endpoints que você usa pra atribuir o badge assim que a compra é confirmada.

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 badge Premium é 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

  1. API Key da Cativa: gerada no Console (Developers > API Keys). Veja Quick Start: API Key. Todas as chamadas usam Authorization: Bearer cativa_live_....
  2. 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.
  3. 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.
  4. 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

Você é o intermediário entre o gateway e a Cativa. Isso te dá controle pra:
  • 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.
E você também pode opcionalmente subscrever o webhook da Cativa user_received_badge pra disparar email de boas-vindas, atualizar CRM, ou registrar evento no analytics.

Implementação

1

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):
Sempre verifique a assinatura do webhook do gateway antes de confiar nos dados. Sem isso, qualquer um que descobrir sua URL pode liberar badges arbitrários.
2

Resolver ou criar o usuário na Cativa pelo email

Duas situações:Caso A, o comprador já tem conta na Cativa: ache o User.Id dele pelo email com GET /admin/users/email/{email}.
Resposta 200 OK (ilustrativa; schema completo na API Reference, tag Users):
Se preferir evitar uma chamada por compra, mantenha uma tabela local email → cativa_user_id populada pelo webhook user_created da Cativa e faça o lookup local:
Caso B, o comprador ainda não tem conta na Cativa: o lookup acima responde 404. Você tem duas opções:
  • Criar direto via API com POST /admin/users (schema na API Reference, tag Users): cria a conta na hora e devolve o id, que você já usa pra atribuir o badge.
  • Convidar e completar depois: registre a intenção em pendingGrants, envie o link de cadastro do tenant e complete a atribuição quando o webhook user_created chegar (ver step 4).
3

Atribuir o badge

Mapeie o productId do gateway pro badgeId da Cativa configurado no Console.A atribuição de badge via API Key de parceiro está disponível. Você tem duas opções:
  • Atribuir por email (POST /admin/membership/badges/{badgeId}/users/by-email): não precisa resolver o userId antes; a Cativa faz o match pelo email do comprador. Ideal pro webhook, onde você só tem o email.
  • Atribuir por id (POST /admin/membership/badges/{badgeId}/users/{userId}): quando você já tem o userId (ex: veio do webhook user_created).
Atribuição por email:
Resposta 200 OK (ilustrativa; schema completo na API Reference, tag Badge):
No fluxo completo do handler, com o userId já resolvido:
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. Ainda assim, a checagem de purchaseId acima evita chamadas redundantes e ajuda na conciliação.
4

(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
Veja Cadastrando e verificando webhooks para o passo-a-passo de cadastro do listener e verificação HMAC. O payload do evento está em user_received_badge e tem esta forma (ilustrativa):
Esqueleto do receiver:

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á disponível, DELETE /admin/membership/badges/{badgeId}/users/{userId}. Veja o schema na aba API Reference (tag Badge). A remoção também é idempotente: remover um badge que já não está atribuído responde sucesso sem erro.
Remover o badge é o suficiente, o acesso ao grupo, curso e espaços atrelados ao badge some imediatamente.

Erros comuns

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:
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).
A atribuição de badge na Cativa é idempotente: aplicar o mesmo badge duas vezes resulta no mesmo estado final. Mas por garantia, salve o purchaseId do gateway numa tabela local e cheque antes:
Isso também ajuda a auditar/conciliar mais tarde (ex: relatório financeiro vs concessões).
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.
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.
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.