Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks são a forma da Cativa te avisar quando algo acontece — em vez de você ficar perguntando à API a cada minuto. Esta página é a visão de alto nível. Para o passo a passo de cadastro, veja Cadastrando webhooks.

​
Como funciona

Quando algo relevante acontece num tenant (usuário recebe badge, post é criado, pagamento é confirmado), a Cativa monta o payload do evento e faz POST no seu endpoint público com Content-Type: application/json. 
Ação no tenant
       │
       ▼
Cativa monta o payload
       │
       ▼
POST https://seu-app.com/webhooks/cativa
Você cadastra a URL e os tipos de evento que quer escutar no painel da Cativa, em Console > Automations > Webhooks. Cada disparo vem com headers X-Cativa-Execution-Id e X-Cativa-Automation-Id que você pode usar para correlacionar com os logs do Console.

​
Garantias de entrega

At-least-once

Cada evento é entregue pelo menos uma vez. Sempre use o ID do evento para idempotência no seu lado, evitando processar duas vezes em caso de duplicata.

Ordem NÃO garantida

Eventos podem chegar fora da ordem em que aconteceram. Não escreva código que depende de receber user_created antes de user_received_badge — eles podem inverter.

​
Por que sem ordem?

A Cativa entrega eventos em paralelo para chegar rápido ao seu endpoint. Forçar ordem reduziria o throughput em ordem de magnitude. Em vez disso, o payload de cada evento contém todos os dados que você precisa para processá-lo isoladamente.

​
Formato do payload

Diferente de muitas APIs, o payload não usa um envelope genérico ({id, type, data}). Cada evento tem um shape próprio em PascalCase, com CustomerId no nível raiz para roteamento multi-tenant.
Exemplo (payload de user_received_badge): 
{
  "CustomerId": "01HQ0...",
  "BadgeId": "01HQ4...",
  "BadgeName": "Premium",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "DisplayName": "Maria Silva"
  },
  "ReceivedAt": "2026-05-08T14:32:01Z"
}
Os campos comuns ao envelope de qualquer evento:
CampoDescrição
CustomerIdID do tenant que originou o evento. Use para rotear quando seu endpoint recebe webhooks de múltiplos tenants.
Campos específicosCada evento adiciona seus próprios campos (ex: BadgeId, BadgeName, User, ReceivedAt para user_received_badge). Veja a página de cada evento para o shape exato.

​
Catálogo de eventos

A Cativa expõe eventos para as ações principais da plataforma. Comece pelo evento canônico:

user_received_badge

Disparado quando um badge é atribuído a um usuário. Página de referência completa com payload e exemplo de receiver.

user_created

Novo usuário cadastrado.

user_joined_group

Usuário entrou num grupo (manual ou via badge).

post_created

Novo post publicado num grupo.

paywall_payment_completed

Pagamento do paywall concluído com sucesso.

​
Antipattern: processar eventos síncronamente no endpoint

Não faça operações lentas (chamadas HTTP, queries pesadas, geração de relatórios) dentro do handler do webhook. Volte um 2xx o mais rápido possível e processe em background.O padrão correto: o endpoint enfileira o evento na sua própria fila e responde 200. Um worker do seu lado processa depois, com calma.
app.post('/webhooks/cativa', express.json(), async (req, res) => {
  // Enfileira para processar depois — não processa aqui
  await myQueue.enqueue(req.body);
  res.status(200).send('ok');
});

​
Idempotência no seu lado

Como entrega é at-least-once, você precisa detectar duplicatas. Use uma combinação de campos do payload (ex: CustomerId + BadgeId + User.Id + ReceivedAt para user_received_badge) ou correlacione com o header X-Cativa-Execution-Id recebido junto com o request: 
async function processEvent(executionId, payload) {
  const alreadyProcessed = await db.events.exists(executionId);
  if (alreadyProcessed) return;

  await db.transaction(async (tx) => {
    await applyBusinessLogic(tx, payload);
    await tx.events.insert({ id: executionId, processedAt: new Date() });
  });
}
Salvar o identificador de execução na mesma transação da lógica de negócio garante que ou tudo aconteceu, ou nada aconteceu — sem chance de processar duas vezes.

​
Próximos passos

Cadastrando webhooks

Como cadastrar um listener no Console e auditar disparos.

user_received_badge

Página de referência completa de um evento — exemplo concreto de payload e receiver.