Skip to main content
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.
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 informando EventName: "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 do POST 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 header X-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 curva 30s → 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.