Webhooks

Webhooks são a forma da Cativa te avisar quando algo acontece, em vez de você ficar perguntando à API a cada minuto. Esta é a visão conceitual. Para o passo a passo de cadastro, verificação de assinatura e retries, veja Cadastrando e verificando webhooks.

Push vs poll: por que webhooks

Sem webhooks, para saber se um usuário recebeu um badge você teria que consultar a API repetidamente e comparar o resultado, um padrão chamado polling. Isso desperdiça requests, atrasa a reação e não escala. Com webhooks, a Cativa empurra o evento para você no instante em que ele acontece. Você reage na hora e só quando há de fato algo novo.

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.

Uma ação acontece no tenant

Um usuário se cadastra, ganha um badge, publica um post ou conclui um pagamento.

A Cativa monta o payload

A plataforma enriquece o evento com os dados que você precisa para processá-lo isoladamente (usuário, badge, pagamento, etc.).

A Cativa assina e faz POST no seu endpoint

O disparo vai com os headers X-Cativa-Signature, X-Cativa-Execution-Id e X-Cativa-Automation-Id.

Seu endpoint verifica, enfileira e responde 200

Você confere a assinatura HMAC, deduplica pelo X-Cativa-Execution-Id, enfileira o processamento e devolve 2xx rápido.

Você cadastra a URL e os tipos de evento que quer escutar no painel da Cativa, em Console > Webhooks. Cada listener recebe um secret próprio (formato whsec_ mais 64 caracteres hex), usado para assinar todo disparo daquele listener.

Headers de cada disparo

Header	Descrição
`X-Cativa-Signature`	Assinatura HMAC-SHA256 do disparo, no formato `t=<unixTs>,v1=<hex>`. Verifique antes de processar.
`X-Cativa-Execution-Id`	ID único deste evento. Estável entre retries do mesmo evento. Use como chave de idempotência.
`X-Cativa-Automation-Id`	ID do listener configurado no Console. O mesmo valor para todos os disparos daquele cadastro.

Garantias de entrega

At-least-once

Cada evento é entregue pelo menos uma vez. Sempre use o X-Cativa-Execution-Id 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.

Assinatura HMAC (X-Cativa-Signature)

Todo disparo é assinado com HMAC-SHA256 usando o secret do listener. Você confere a assinatura antes de processar o evento, garantindo que o request veio mesmo da Cativa e que o body não foi adulterado em trânsito. A assinatura chega no header:

X-Cativa-Signature: t=1715177521,v1=8c1d4e2a3b5f4d8a9c6e7f0b1a2d3e4f8a9c6e7f0b1a2d3e4f8a9c6e7f0b1a2d

t é o timestamp Unix (em segundos) do momento do disparo.
v1 é a assinatura HMAC-SHA256 (hex) sobre a string "<t>.<rawBody>", usando o secret do listener como chave.

O exemplo de verificação completo (Node, Python, Go, C#) está em Cadastrando e verificando webhooks.

Compute o HMAC sobre o body bruto (a string exata recebida), não sobre o JSON re-serializado. Re-serializar muda espaços em branco e ordem de chaves, o que invalida a assinatura.

Reentrega com backoff

Se seu endpoint não responder com 2xx, a Cativa re-tenta de acordo com a curva:

30s  →  5min  →  30min  →  2h  →  6h  →  24h

São 6 retries após a tentativa inicial, 7 entregas no total, cobrindo cerca de 33 horas. A Cativa respeita o header Retry-After que você retornar (até o limite máximo da próxima janela do backoff).

Quando re-tenta vs falha permanente

Status	Comportamento
`2xx`	Sucesso, sem retry
`408 Request Timeout`	Retry
`429 Too Many Requests`	Retry (respeita `Retry-After`)
`5xx` (500, 502, 503, 504, …)	Retry
Erros de rede / timeouts TCP	Retry
`400 Bad Request`	Falha permanente, sem retry
`401 Unauthorized`	Falha permanente, sem retry
`403 Forbidden`	Falha permanente, sem retry
`404 Not Found`	Falha permanente, sem retry
`410 Gone`	Falha permanente, sem retry

Se todas as tentativas falharem, o disparo é registrado internamente como falho. A v1 ainda não tem painel no Console para inspecionar entregas falhas. Entre em contato com o suporte da Cativa para investigar.

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": "01HQ0ABCDEF1234567890XYZ",
  "BadgeId": "01HQ4ABCDEF1234567890XYZ",
  "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:

Campo	Descrição
`CustomerId`	ID do tenant que originou o evento. Use para rotear quando seu endpoint recebe webhooks de múltiplos tenants.
Campos específicos	Cada 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 receiver de exemplo.

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.

A lista completa de eventos disponíveis (incluindo comment_created, course_completed, lesson_completed e user_received_private_message, com página de referência em breve) está em Cadastrando e verificando webhooks.

Antipattern: processar eventos de forma síncrona 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 a entrega é at-least-once, você precisa detectar duplicatas. Use o header X-Cativa-Execution-Id (sempre enviado e estável entre retries do mesmo evento) como chave de deduplicação:

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 e verificando webhooks

Como cadastrar listener, verificar HMAC e lidar com retries, com exemplos em Node, Python, Go e C#.

user_received_badge

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

Erros e limites de taxa

A mesma curva de backoff, aplicada quando você chama a API e recebe 429 ou 5xx.

Links de pagamento e assinaturas

De onde vem o evento paywall_payment_completed e o que ele libera.

Comece aqui

Conceitos

Guias

Changelog

Webhooks

Push vs poll: por que webhooks

Como funciona

Headers de cada disparo

Garantias de entrega

At-least-once

Ordem NÃO garantida

Por que sem ordem

Assinatura HMAC (X-Cativa-Signature)

Reentrega com backoff

Quando re-tenta vs falha permanente

Formato do payload

Catálogo de eventos

user_received_badge

user_created

user_joined_group

post_created

paywall_payment_completed

Antipattern: processar eventos de forma síncrona no endpoint

Idempotência no seu lado

Próximos passos

Cadastrando e verificando webhooks

user_received_badge

Erros e limites de taxa

Links de pagamento e assinaturas

​Push vs poll: por que webhooks

​Como funciona

​Headers de cada disparo

​Garantias de entrega

At-least-once

Ordem NÃO garantida

​Por que sem ordem

​Assinatura HMAC (X-Cativa-Signature)

​Reentrega com backoff

​Quando re-tenta vs falha permanente

​Formato do payload

​Catálogo de eventos

user_received_badge

user_created

user_joined_group

post_created

paywall_payment_completed

​Antipattern: processar eventos de forma síncrona no endpoint

​Idempotência no seu lado

​Próximos passos

Cadastrando e verificando webhooks

user_received_badge

Erros e limites de taxa

Links de pagamento e assinaturas

Push vs poll: por que webhooks

Como funciona

Headers de cada disparo

Garantias de entrega

Por que sem ordem

Assinatura HMAC (X-Cativa-Signature)

Reentrega com backoff

Quando re-tenta vs falha permanente

Formato do payload

Catálogo de eventos

Antipattern: processar eventos de forma síncrona no endpoint

Idempotência no seu lado

Próximos passos