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

Para consultar o catálogo completo derivado do esquema, consulte todos os exemplos.

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/1.1 200 OK

Para configuração do endpoint, validação de assinatura e comportamento de repetição, consulte Configurar webhooks.

Participante adicionado

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

Requisição

{
  "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/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

{
  "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/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

{
  "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/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

Primeiros passos

Guias

Endpoints

Webhooks

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

O que é

Antes de começar

Como funciona

Requisição

Resposta

Participante adicionado

Requisição

Resposta

Explicação

Solicitação de entrada criada

Requisição

Resposta

Explicação

Falha na remoção do participante

Requisição

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Participante adicionado

​Requisição

​Resposta

​Explicação

​Solicitação de entrada criada

​Requisição

​Resposta

​Explicação

​Falha na remoção do participante

​Requisição

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Requisição

Resposta

Participante adicionado

Requisição

Resposta

Explicação

Solicitação de entrada criada

Requisição

Resposta

Explicação

Falha na remoção do participante

Requisição

Resposta

Explicação