# group.joined

Fonte: https://apiwpp.com/docs/webhooks/group-joined
Seção: Webhooks
Atualizado em: 2026-09-28

O número entrou num grupo.

`POST` para o `webhookBaseUrl` do projeto.

O número da conexão entrou num grupo ou foi adicionado a um. Também é enviado uma vez para cada grupo de que o número já participa quando a conexão dele abre pela primeira vez neste processo do gateway, e não de novo nas reconexões seguintes.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente, pela chave `data.groupId`.

**Não é só entrada nova.** O anúncio dos grupos existentes volta a acontecer quando a conexão abre num processo novo do gateway (depois de um reinício ou de uma mudança de instância) e depois de um novo pareamento que segue um logout. Por isso, trate `group.joined` como “o número está neste grupo” e grave o grupo com um *upsert* por `groupId`, nunca como uma inserção que falha ou duplica.

**Campos opcionais.** `groupName` e `participantCount` ficam fora do objeto quando o gateway não os conhece (por exemplo, quando o WhatsApp não devolve os dados do grupo no momento da entrada). Só `groupId` vem sempre. Para ter a lista atual, com nome e tamanho, use [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos).

**O ciclo de um grupo.** Uma mudança de nome chega como [`group.updated`](https://apiwpp.com/docs/webhooks/group-updated), e a remoção do número como [`group.left`](https://apiwpp.com/docs/webhooks/group-left). As mensagens do grupo chegam como [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming), com `jid` igual ao `groupId` e `phone` sempre `null`.

**Entrega.** Um `POST` com `Content-Type: application/json` ao `webhookBaseUrl` do projeto, feito **pelo menos uma vez**; um projeto inativo não recebe webhooks. Responda `2xx` em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (`3xx`) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, **6 tentativas** no total, e então fica `dead`. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica `dead`. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo `timestamp` do envelope. Reenvie as entregas `dead` com [`POST /webhooks/deliveries/{id}/resend`](https://apiwpp.com/docs/api/registros/reenviar-entrega) ou [`POST /webhooks/deliveries/resend-dead`](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas).

**Assinatura.** `X-Webhook-Token` vem sempre, com o `webhookToken` do projeto, junto com os `webhookHeaders` personalizados. Com um `webhookSecret`, cada tentativa também traz `X-Sales-Timestamp` (segundos unix da tentativa) e `X-Sales-Signature`: calcule `"sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo))` sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um `X-Sales-Timestamp` a mais de 300 segundos do seu relógio. Veja [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## Cabeçalhos da entrega

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `X-Webhook-Token` | `string` | sim | O `webhookToken` do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto). Os `webhookHeaders` personalizados do projeto também são enviados. |
| `X-Sales-Timestamp` | `string` | não | Só quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio. (formato `^\d+$`) |
| `X-Sales-Signature` | `string` | não | Só quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante. (formato `^sha256=[0-9a-f]{64}$`) |

## Envelope

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | `string` | sim | O tipo do evento, que decide o formato de `data`. Ignore os tipos que você não conhece: a lista de eventos pode crescer. (sempre "group.joined") |
| `connectionId` | `string · uuid` | sim | O id (UUID) da conexão, ou seja, do número, que gerou o evento. |
| `tenantId` | `string · uuid` | sim | O id (UUID) do projeto dono da conexão. |
| `externalId` | `string \| null` | sim | O `externalId` que você informou ao criar a conexão, para ligá-la a um registro seu. `null` quando a conexão foi criada sem ele. |
| `timestamp` | `string · date-time` | sim | Quando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho `X-Sales-Timestamp`. |

## Campos de `data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `groupId` | `string` | sim | O JID do grupo (`…@g.us`). É o mesmo valor que chega em `jid` nas mensagens do grupo e que serve de `to` para enviar ao grupo. |
| `groupName` | `string` | não | O nome (assunto) do grupo. Fica fora do objeto quando não é conhecido. |
| `participantCount` | `number` | não | Quantos participantes o grupo tem, contando o próprio número. Fica fora do objeto quando não é conhecido. |

## Exemplo

```json
{
  "type": "group.joined",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "groupId": "120363040000000001@g.us",
    "groupName": "Equipe da barbearia",
    "participantCount": 3
  }
}
```

Guia: [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
