paywall_payment_completed

Esse evento é disparado assim que o gateway de pagamento (Asaas, Stripe, etc.) confirma um pagamento de paywall. É o momento canônico para sincronizar liberação de acesso em sistemas externos (área de membros, plataforma de cursos legada, ERP), já que internamente o Cativa também usa esse mesmo evento para conceder badge/grupo/curso ao usuário.

O nome interno do evento (usado nos cadastros de webhook do Console) é paywall_payment_completed.

Assinar este evento

Aponte um listener para a sua URL informando EventName: "paywall_payment_completed". Auth, secret e verificação em Cadastrando e verificando webhooks.

curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/integration/01HQ0ABCDEF1234567890XYZ/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "EventName": "paywall_payment_completed",
    "Url": "https://meuapp.com/webhooks/cativa",
    "IsActive": true
  }'

Quando dispara

Gateway de pagamento (Asaas, Stripe) envia callback de confirmação para o Cativa
Pagamento PIX é compensado
Cobrança de boleto é compensada
Cobrança de cartão de crédito é capturada com sucesso
Pagamento manual é marcado como confirmado no admin

Quando NÃO dispara

Pagamento criado mas ainda pendente (PIX gerado e não pago, boleto não vencido, etc.)
Pagamento falho ou cancelado pelo gateway
Pagamento estornado / refundado depois de já ter sido confirmado
Pagamento sem UserId resolvido (ex: PIX onde o pagador ainda não foi associado a um usuário do tenant), entrega é pulada
Paywall ou pagamento não encontrados no enriquecimento do payload (entrega é pulada)

Payload

O payload é serializado em PascalCase e enviado no body do POST com Content-Type: application/json. O payload tem três objetos aninhados, User, Paywall e Payment:

{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "FirstName": "Maria",
    "LastName": "Silva",
    "DisplayName": "Maria Silva",
    "Username": "maria.silva",
    "CreatedAt": "2026-04-12T14:32:01Z"
  },
  "Paywall": {
    "Id": "01HQ5PAYWALL1234567890ABC",
    "Name": "Mentoria Premium 2026",
    "Description": "Acesso de 12 meses à mentoria, cursos exclusivos e grupo VIP.",
    "CustomLink": "mentoria-premium-2026",
    "FullUrl": "https://comunidade.exemplo.com/pagamento/mentoria-premium-2026",
    "Price": 1497.00,
    "DiscountPercentage": 10,
    "MaxInstallments": 12,
    "AccessMonths": 12,
    "RemoveAfterExpiration": true,
    "ActionType": 5,
    "ActionPayload": "01HQ4ABCDEF1234567890XYZ",
    "ImageUrl": "https://cdn.cativalab.digital/paywall/01HQ5.../cover.jpg",
    "OpeningLink": "https://comunidade.exemplo.com/boas-vindas-mentoria"
  },
  "Payment": {
    "PaymentId": "01HQ9PAYMENT1234567890XYZ",
    "ValorPago": 1347.30,
    "ValorOriginal": 1497.00,
    "Desconto": 10,
    "Installments": 12,
    "TipoPagamento": "CREDIT_CARD",
    "Gateway": "Asaas",
    "IdTransacao": "pay_5478392a01b2c3d4e5f6",
    "CompletedAt": "2026-05-08T14:32:01Z"
  }
}

Campos do payload

Raiz

Campo	Tipo	Descrição
`CustomerId`	GUID	ID do tenant que originou o evento.
`User`	object	Dados do comprador.
`Paywall`	object	Configuração do paywall que foi pago.
`Payment`	object	Detalhes do pagamento confirmado.

`User`

Campo	Tipo	Descrição
`User.Id`	GUID	ID do usuário comprador.
`User.Email`	string	Email do comprador.
`User.FirstName`	string	Primeiro nome.
`User.LastName`	string	Sobrenome.
`User.DisplayName`	string	Nome de exibição.
`User.Username`	string	Nome de usuário.
`User.CreatedAt`	ISO 8601	Quando o usuário foi criado no tenant.

`Paywall`

Campo	Tipo	Descrição
`Paywall.Id`	GUID	ID do paywall.
`Paywall.Name`	string	Nome configurado do paywall.
`Paywall.Description`	string \| null	Descrição livre, quando informada.
`Paywall.CustomLink`	string	Slug usado na URL pública do paywall.
`Paywall.FullUrl`	string \| null	URL pública completa de checkout (`{origem-do-tenant}/pagamento/{CustomLink}`). `null` quando o tenant não tem origem configurada.
`Paywall.Price`	decimal	Preço cheio configurado (na moeda do tenant, geralmente BRL).
`Paywall.DiscountPercentage`	int	Percentual de desconto vigente no paywall (0-100).
`Paywall.MaxInstallments`	int	Número máximo de parcelas permitido pelo paywall.
`Paywall.AccessMonths`	int \| null	Quantidade de meses de acesso concedidos pela compra. `null` para acesso vitalício.
`Paywall.RemoveAfterExpiration`	bool	Se `true`, o acesso é removido automaticamente quando o `AccessMonths` expira.
`Paywall.ActionType`	int	Ação executada após o pagamento (ver tabela abaixo).
`Paywall.ActionPayload`	string \| null	Carga associada à `ActionType`, tipicamente um ID (de badge, curso ou grupo) ou JSON, conforme o tipo.
`Paywall.ImageUrl`	string \| null	Imagem de capa do paywall, quando configurada.
`Paywall.OpeningLink`	string \| null	Link para onde o usuário é redirecionado após a compra, quando configurado.

Paywall.ActionType segue o enum:

Valor	Significado	`ActionPayload`
`0`	`CreateUserOnly`, apenas registra o usuário, sem conceder acesso	vazio
`1`	`AddToCourse`, matricula em um curso	`CourseId` (GUID)
`2`	`GrantBadge`, atribui um badge	`BadgeId` (GUID)
`3`	`AddToGroup`, adiciona a um grupo	`GroupId` (GUID)
`4`	`AddToCourseAndGrantBadge`	JSON com `CourseId` + `BadgeId`
`5`	`AddToGroupAndGrantBadge`	JSON com `GroupId` + `BadgeId`
`6`	`None`, nenhuma ação automática	vazio

`Payment`

Campo	Tipo	Descrição
`Payment.PaymentId`	GUID	ID do pagamento confirmado.
`Payment.ValorPago`	decimal	Valor efetivamente pago após descontos.
`Payment.ValorOriginal`	decimal	Valor cheio do paywall antes de descontos.
`Payment.Desconto`	int	Percentual de desconto aplicado neste pagamento (0-100).
`Payment.Installments`	int	Número de parcelas escolhido pelo comprador.
`Payment.TipoPagamento`	string	Forma de pagamento, valores típicos: `PIX`, `CREDIT_CARD`, `BOLETO`. Normalizado em maiúsculo.
`Payment.Gateway`	string	Gateway que processou (ex: `Asaas`, `Stripe`). String vazia se não informado.
`Payment.IdTransacao`	string	ID externo da transação no gateway (use para conciliação). String vazia se não informado.
`Payment.CompletedAt`	ISO 8601	Momento da confirmação do pagamento.

Os nomes em português (ValorPago, ValorOriginal, Desconto, TipoPagamento, IdTransacao) são herdados da v1 da plataforma e mantidos para compatibilidade com integrações Make/Zapier existentes. Não vão ser renomeados.

Headers do request

Header	Descrição
`X-Cativa-Signature`	Assinatura HMAC-SHA256 do disparo, no formato `t=<unixTs>,v1=<hex>`. Verifique antes de processar o evento.
`X-Cativa-Idempotency-Key`	Chave canônica de deduplicação. Igual em todos os retries da mesma entrega.
`X-Cativa-Execution-Id`	ID único deste evento. Estável entre retries, use como chave de idempotência.
`X-Cativa-Automation-Id`	ID do listener configurado no Console (mesmo valor para todos os disparos do mesmo cadastro).

A explicação completa de como verificar X-Cativa-Signature, lidar com retries e garantir idempotência (com exemplos em Node, Python, Go e C#) está em Cadastrando e verificando webhooks.

Casos de uso

Liberar acesso em plataforma externa, se você ainda hospeda parte do conteúdo fora do Cativa (área de membros legada, Hotmart, Memberkit), use Payment.PaymentId + User.Id para liberar acesso lá assim que o pagamento for confirmado.
Conciliação financeira, registrar Payment.IdTransacao + Payment.Gateway + Payment.ValorPago no seu ERP/contabilidade para fechar o caixa por gateway.
Disparar email transacional, enviar recibo, NF-e ou boas-vindas de “compra confirmada” usando User.Email, Paywall.Name, Payment.ValorPago e Payment.Installments.

Esse evento dispara uma vez por pagamento confirmado, ele não dispara em renovação automática de assinatura (cobrança recorrente ainda não está em produção). Não trate este evento como gatilho de renovação.

Reagindo ao evento

Depois de verificar a assinatura, libere o acesso na sua plataforma externa. O Payment.PaymentId é único por pagamento confirmado, então serve de chave de idempotência. O Paywall.ActionType diz o que a compra concede (ver a tabela do enum acima):

async function onPaywallPaymentCompleted(event) {
  const { User, Paywall, Payment } = event;

  // Idempotência: já liberou este pagamento? Sai.
  if (await db.grants.exists(Payment.PaymentId)) return;

  // ActionType 5 = AddToGroupAndGrantBadge
  if (Paywall.ActionType === 5) {
    await externalPlatform.grantAccess({
      userEmail: User.Email,
      product: Paywall.Name,
      months: Paywall.AccessMonths, // null = acesso vitalício
    });
  }

  await db.grants.insert({ id: Payment.PaymentId, at: new Date() });
}

Eventos relacionados

user_received_badge

Disparado quando o paywall concede badge, útil para casar a permissão recebida com o pagamento.

user_joined_group

Disparado quando o paywall adiciona o comprador a um grupo (ActionType 3 ou 5).

Cadastrando webhooks

Como cadastrar listeners, verificar HMAC e lidar com retries.

Webhooks (visão geral)

Por que webhooks, garantias de entrega e formato dos payloads.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Raiz

`User`

`Paywall`

`Payment`

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados

user_received_badge

user_joined_group

Cadastrando webhooks

Webhooks (visão geral)

​Assinar este evento

​Quando dispara

​Quando NÃO dispara

​Payload

​Campos do payload

​Raiz

​User

​Paywall

​Payment

​Headers do request

​Casos de uso

​Reagindo ao evento

​Eventos relacionados

user_received_badge

user_joined_group

Cadastrando webhooks

Webhooks (visão geral)

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Raiz

`User`

`Paywall`

`Payment`

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados