# group.updated

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

Um grupo do número mudou.

`POST` para o `webhookBaseUrl` do projeto.

Um grupo de que o número participa mudou: o nome, a descrição, o link de convite ou uma configuração (quem envia mensagens, quem edita os dados do grupo, quem adiciona participantes, a aprovação de novos membros). O evento só diz qual foi o grupo e, quando o nome mudou, o nome novo em `groupName`.

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

**Sem `groupName`, a mudança foi em outra coisa.** O evento não diz o que mudou além do nome. Para consultar o nome e o tamanho atuais de todos os grupos, use [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos).

**Também chega sem que nada tenha mudado.** Sempre que o gateway busca no WhatsApp a lista completa de grupos do número, ele envia um `group.updated` por grupo, com o nome atual em `groupName`: quando a conexão abre (também nas reconexões), a cada chamada de [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos) e quando o WhatsApp avisa que a lista de grupos mudou. Trate `groupName` como o nome atual do grupo, e não como o registro de uma renomeação.

**Participantes não contam.** Entradas, saídas e promoções a administrador de outros participantes não geram este evento. Quando é o próprio número que entra ou sai, chegam [`group.joined`](https://apiwpp.com/docs/webhooks/group-joined) e [`group.left`](https://apiwpp.com/docs/webhooks/group-left).

**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.updated") |
| `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`) que mudou. |
| `groupName` | `string` | não | O nome (assunto) atual do grupo. Fica fora do objeto quando a mudança não foi no nome. |

## Exemplo

```json
{
  "type": "group.updated",
  "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 2026"
  }
}
```

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