user_joined_group

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.

Assinar este evento

Aponte um listener para a sua URL informando EventName: "user_joined_group". Para escutar só um grupo, adicione o GroupId no corpo. Auth, secret e verificação em Cadastrando e verificando webhooks.

curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/integration/01HQ0ABCDEF1234567890XYZ/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "EventName": "user_joined_group",
    "Url": "https://meuapp.com/webhooks/cativa",
    "IsActive": true
  }'

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

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.
`GroupId`	GUID	ID do grupo em que o usuário entrou.
`GroupName`	string	Nome do grupo no momento do evento (snapshot, não muda se o nome for editado depois).
`User.Id`	GUID	ID do usuário que entrou no grupo.
`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.
`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.
`User.Badges`	GUID[]	Lista completa de badges do usuário no momento do evento.
`JoinedAt`	ISO 8601	Quando 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

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-Idempotency-Key`	Chave canônica de deduplicação. Igual em todos os retries da mesma entrega.
`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).

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.

Reagindo ao evento

Depois de verificar a assinatura, espelhe a entrada no seu workspace externo. O exemplo mapeia o GroupId da Cativa para um canal (Discord/Slack) e adiciona o membro:

const CHANNEL_BY_GROUP = {
  '01HQ2GROUP1234567890XYZAB': 'discord-canal-mentoria',
};

async function onUserJoinedGroup(event) {
  const { GroupId, GroupName, User } = event;

  const channelId = CHANNEL_BY_GROUP[GroupId];
  if (!channelId) return; // grupo sem canal espelhado

  await chat.addMemberToChannel(channelId, {
    email: User.Email,
    displayName: User.DisplayName,
    welcome: `Bem-vindo(a) ao ${GroupName}!`,
  });
}

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.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados

user_received_badge

user_created

Cadastrando webhooks

Webhooks (visão geral)

​Assinar este evento

​Quando dispara

​Quando NÃO dispara

​Payload

​Campos do payload

​Headers do request

​Casos de uso

​Reagindo ao evento

​Eventos relacionados

user_received_badge

user_created

Cadastrando webhooks

Webhooks (visão geral)

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados