> ## 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.

# user_joined_group

> Disparado quando um usuário entra num grupo da comunidade — voluntariamente, por convite, por automação de badge ou por importação em lote.

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.

<Note>
  O nome interno do evento (usado nos cadastros de webhook do Console) é `user_joined_group`.
</Note>

## 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`:

```json theme={null}
{
  "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.                                                                          |

<Note>
  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.
</Note>

## 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).                   |

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](/pt-BR/webhooks/subscribing-and-verifying).

## 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

<CardGroup cols={2}>
  <Card title="user_received_badge" icon="shield-check" href="/pt-BR/webhooks/events/user-received-badge">
    Disparado quando o usuário ganha um badge — frequentemente o gatilho que leva à entrada no grupo.
  </Card>

  <Card title="user_created" icon="user-plus" href="/pt-BR/webhooks/events/user-created">
    Disparado quando o usuário é criado no tenant pela primeira vez.
  </Card>

  <Card title="Cadastrando webhooks" icon="webhook" href="/pt-BR/webhooks/subscribing-and-verifying">
    Como cadastrar listeners, verificar HMAC e lidar com retries.
  </Card>

  <Card title="Webhooks (visão geral)" icon="rectangle-history" href="/pt-BR/concepts/webhooks">
    Por que webhooks, garantias de entrega e formato dos payloads.
  </Card>
</CardGroup>