> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exemplos de Webhook de atualização de participantes do grupo do WhatsApp

> Processe atualizações de participantes do grupo e de solicitações de entrada do WhatsApp.

<Note>Para consultar o catálogo completo derivado do esquema, consulte [todos os exemplos](/pt/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## O que é

Processe atualizações de participantes do grupo e de solicitações de entrada do WhatsApp.

## Antes de começar

* Crie um endpoint HTTPS público em sua aplicação.
* Configure um endpoint de webhook da YCloud para os tipos de eventos necessários.
* Armazene o segredo de assinatura do endpoint com segurança.
* Torne o processamento de eventos idempotente.

## Como funciona

A YCloud envia uma requisição HTTP `POST` quando o evento ocorre. Verifique a assinatura, registre o evento de forma durável, retorne uma resposta `2xx` e processe tarefas lentas de forma assíncrona.

## Requisição

Os cenários abaixo mostram requisições entregues à sua URL de webhook. Trate o identificador de evento `id` como o identificador de entrega e use `type` para rotear a carga útil.

## Resposta

Retorne um status `2xx` após aceitar o evento.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>Para configuração do endpoint, validação de assinatura e comportamento de repetição, consulte [Configurar webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

<br />

## Participante adicionado

Quando um participante é adicionado a um grupo do WhatsApp, você receberá um webhook com a seguinte estrutura de carga útil:

### Requisição

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "invite_link",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "addedParticipants": [
      {
        "input": "US.abc123",
        "waId": "16315551111",
        "recipientUserId": "US.abc123",
        "parentRecipientUserId": "US.parent123"
      }
    ],
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}
```

### Resposta

Confirme a entrega após aceitar o evento de forma durável.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explicação

Roteie o evento por `type`, remova duplicatas usando `id` e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

## Solicitação de entrada criada

Quando um usuário solicita entrada em um grupo do WhatsApp que requer aprovação, você receberá um webhook com a seguinte estrutura de carga útil:

### Requisição

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_participants_124",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_join_request_created",
    "status": "requested",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "admin_approval",
    "joinRequestId": "join-request-id",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    }
  }
}
```

### Resposta

Confirme a entrega após aceitar o evento de forma durável.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explicação

Roteie o evento por `type`, remova duplicatas usando `id` e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

## Falha na remoção do participante

Quando a remoção de um ou mais participantes falhar ou for parcialmente concluída, você receberá um webhook com a seguinte estrutura de carga útil:

### Requisição

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_participants_125",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "requestId": "REQ_REMOVE",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "initiatedBy": "business",
    "removedParticipants": [
      {
        "input": "16315551111"
      }
    ],
    "failedParticipants": [
      {
        "input": "16315552222",
        "errors": [
          {
            "code": 131212,
            "title": "Participant cannot be removed"
          }
        ]
      }
    ],
    "errors": [
      {
        "title": "Not all participants were removed"
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}
```

### Resposta

Confirme a entrega após aceitar o evento de forma durável.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explicação

* **type**: Sempre `whatsapp.group.participants_update` para eventos de participantes de grupo e solicitações de entrada
* **whatsappGroup**: Contém os detalhes da atualização do participante do grupo ou da solicitação de entrada
  * **field**: Sempre `group_participants_update`
  * **type**: O tipo de evento do participante, como `group_participants_add`, `group_participants_remove`, `group_join_request_created` ou `group_join_request_revoked`
  * **status**: O status do evento normalizado, como `added`, `removed`, `left`, `requested`, `revoked` ou `failed`
  * **groupId**: O ID do grupo do WhatsApp
  * **reason**: O motivo do evento do participante ou da solicitação de entrada
  * **joinRequestId**: O ID da solicitação de entrada, incluído em eventos de solicitação de entrada
  * **initiatedBy**: Indica quem iniciou um evento de remoção, como `business` ou `participant`
  * **recipientUserId** e **parentRecipientUserId**: IDs de usuário com escopo de negócios para o participante afetado
  * **addedParticipants**, **removedParticipants** e **failedParticipants**: Detalhes no nível do participante para atualizações em lote ou com resultados parciais

<br />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.