Esse evento é disparado toda vez que um badge é atribuído a um usuário, seja por compra, atribuição manual no admin, ou via API.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.
O nome interno do evento (usado nos cadastros de webhook do Console) é
user_received_badge.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
| Campo | Tipo | Descrição |
|---|---|---|
CustomerId | GUID | ID do tenant que originou o evento. Use para rotear quando seu endpoint recebe webhooks de múltiplos tenants. |
BadgeId | GUID | ID do badge atribuído. |
BadgeName | string | Nome configurado do badge (ex: Premium). |
User.Id | GUID | ID do usuário que recebeu o badge. |
User.Email | string | Email do usuário. |
User.FirstName | string | Primeiro nome. |
User.LastName | string | Sobrenome. |
User.DisplayName | string | Nome de exibição. |
User.Username | string | Nome de usuário (sem espaços). |
User.PhoneNumber | string | Telefone, quando informado. |
User.CreatedAt | ISO 8601 | Quando o usuário foi criado no tenant. |
User.BadgeId | GUID | null | Badge principal do usuário (compatibilidade — pode ser igual ao BadgeId do nível raiz). |
User.Badges | GUID[] | Lista completa de badges atribuídos ao usuário no momento do evento. |
ReceivedAt | ISO 8601 | Quando a atribuição aconteceu no tenant. |
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-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). |
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.
