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.

Esse evento é disparado toda vez que um usuário passa a fazer parte de um grupo, qualquer que seja o caminho: ele mesmo entrou, foi adicionado por um admin, ganhou acesso porque recebeu um badge, ou veio via importação em lote.
O nome interno do evento (usado nos cadastros de webhook do Console) é user_joined_group.

​
Quando dispara

  • Usuário entra num grupo público pela própria interface da comunidade
  • Usuário aceita um convite para um grupo privado
  • Admin adiciona o usuário manualmente ao grupo
  • Automação de badge concede acesso ao grupo (grupo restrito a determinado badge)
  • Importação em lote (bulk operation) inclui o usuário no grupo
  • Você adiciona o usuário ao grupo via API

​
Quando NÃO dispara

  • Usuário sai do grupo (esse é um evento separado, ainda não exposto via webhook)
  • Pedido de entrada em grupo privado que está pendente de aprovação (só dispara depois que o admin aprova)
  • Re-entrada — se o usuário já é membro do grupo, nada acontece
  • Usuário não encontrado no enriquecimento do payload (entrega é pulada)
  • Operação falha por validação (grupo não existe, usuário banido, etc.)

​
Payload

O payload é serializado em PascalCase e enviado no body do POST com Content-Type: application/json: 
{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "GroupId": "01HQ2GROUP1234567890XYZAB",
  "GroupName": "Mentoria Premium",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "FirstName": "Maria",
    "LastName": "Silva",
    "DisplayName": "Maria Silva",
    "Username": "maria.silva",
    "PhoneNumber": "+5511999998888",
    "CreatedAt": "2026-04-12T14:32:01Z",
    "BadgeId": "01HQ4ABCDEF1234567890XYZ",
    "Badges": [
      "01HQ4ABCDEF1234567890XYZ"
    ]
  },
  "JoinedAt": "2026-05-08T14:32:01Z"
}

​
Campos do payload

CampoTipoDescrição
CustomerIdGUIDID do tenant que originou o evento. Use para rotear quando seu endpoint recebe webhooks de múltiplos tenants.
GroupIdGUIDID do grupo em que o usuário entrou.
GroupNamestringNome do grupo no momento do evento (snapshot — não muda se o nome for editado depois).
User.IdGUIDID do usuário que entrou no grupo.
User.EmailstringEmail do usuário.
User.FirstNamestringPrimeiro nome.
User.LastNamestringSobrenome.
User.DisplayNamestringNome de exibição.
User.UsernamestringNome de usuário.
User.PhoneNumberstringTelefone, quando informado.
User.CreatedAtISO 8601Quando o usuário foi criado no tenant.
User.BadgeIdGUID | nullBadge principal do usuário.
User.BadgesGUID[]Lista completa de badges do usuário no momento do evento.
JoinedAtISO 8601Quando a entrada no grupo aconteceu.
O payload não indica explicitamente o canal pelo qual o usuário entrou (manual, badge, convite, bulk). Se você precisa diferenciar isso, use as condições do listener no Console — por exemplo, criar um listener separado por GroupId ou filtrar por User.Badges para detectar entradas via badge.

​
Headers do request

HeaderDescrição
X-Cativa-SignatureAssinatura HMAC-SHA256 do disparo, no formato t=<unixTs>,v1=<hex>. Verifique antes de processar o evento.
X-Cativa-Execution-IdID único deste evento. Estável entre retries — use como chave de idempotência.
X-Cativa-Automation-IdID do listener configurado no Console (mesmo valor para todos os disparos do mesmo cadastro).
A explicação completa de como verificar X-Cativa-Signature, lidar com retries e garantir idempotência (com exemplos em Node, Python, Go e C#) está em Cadastrando e verificando webhooks.

​
Casos de uso

  • Sincronizar com Discord/Slack — quando alguém entra no grupo “Mentoria Premium”, adicionar automaticamente ao canal correspondente no seu workspace externo.
  • Disparar email contextual — enviar uma mensagem de boas-vindas específica daquele grupo com material introdutório, links e próximos passos.
  • Atualizar segmentação — registrar a entrada num CRM/automação de marketing para que campanhas posteriores reconheçam o usuário como membro do grupo.

​
Eventos relacionados

user_received_badge

Disparado quando o usuário ganha um badge — frequentemente o gatilho que leva à entrada no grupo.

user_created

Disparado quando o usuário é criado no tenant pela primeira vez.

Cadastrando webhooks

Como cadastrar listeners, verificar HMAC e lidar com retries.

Webhooks (visão geral)

Por que webhooks, garantias de entrega e formato dos payloads.