O nome interno do evento (usado nos cadastros de webhook do Console) é
user_received_badge.Assinar este evento
Aponte um listener para a sua URL informandoEventName: "user_received_badge". Auth, secret e verificação em Cadastrando e verificando webhooks.
Quando dispara
- Admin atribui badge manualmente no painel
- Compra externa via webhook do Hotmart/Kiwify dispara atribuição de badge
- Usuário completa um curso e ganha badge automático
- Você mesmo chama a API para atribuir
Quando NÃO dispara
- Atribuição falha (ex: badge não existe no tenant)
- Usuário foi soft-deleted
Payload
O payload é serializado em PascalCase e enviado no body doPOST com Content-Type: application/json:
Campos do payload
Headers do request
A explicação completa de como verificar
X-Cativa-Signature (com exemplos em Node, Python, Go e C#) está em Cadastrando e verificando webhooks.
Receiver de exemplo (Express)
Esse exemplo verifica a assinatura HMAC, descarta requests com timestamp fora da janela anti-replay de 5 minutos, e processa só o que está autenticado:Idempotência
Use o headerX-Cativa-Execution-Id recebido junto com o request para detectar duplicatas (mesmo executionId é enviado em todos os retries de um mesmo evento):
Retries
Se seu endpoint falhar, a Cativa re-tenta na curva30s → 5min → 30min → 2h → 6h → 24h (6 retries, 7 entregas no total, ~33h de cobertura). Códigos 400/401/403/404/410 são tratados como falhas permanentes, não há retry. Veja a tabela completa em Cadastrando e verificando webhooks.
Eventos relacionados
user_joined_group
Disparado quando o usuário entra num grupo (pode ser por badge).
Cadastrando webhooks
Como cadastrar listeners, verificar HMAC e lidar com retries.
