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

# Ejemplos de webhook de actualización de participantes de grupos de WhatsApp

> Gestiona las actualizaciones de participantes y solicitudes de unión a grupos de WhatsApp.

<Note>Para consultar el catálogo exhaustivo derivado del esquema, consulta [todos los ejemplos](/es/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## Qué es

Gestiona las actualizaciones de participantes y solicitudes de unión a grupos de WhatsApp.

## Antes de comenzar

* Crea un endpoint HTTPS público en tu aplicación.
* Configura un endpoint de webhook de YCloud para los tipos de eventos que necesites.
* Almacena el secreto de firma del endpoint de forma segura.
* Haz que el procesamiento de eventos sea idempotente.

## Cómo funciona

YCloud envía una solicitud HTTP `POST` cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta `2xx` y procesa el trabajo lento de forma asíncrona.

## Solicitud

Los siguientes escenarios muestran las solicitudes enviadas a tu URL de webhook. Trata el `id` del evento como el identificador de entrega y usa `type` para enrutar el payload.

## Respuesta

Devuelve un estado `2xx` tras aceptar el evento.

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

<Note>Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta [Configurar webhooks](/es/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

<br />

## Participante añadido

Cuando se añade un participante a un grupo de WhatsApp, recibirás un webhook con la siguiente estructura de payload:

### Solicitud

```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"
  }
}
```

### Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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

### Explicación

Enruta el evento mediante `type`, deduplícalo mediante `id` y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

## Solicitud de unión creada

Cuando un usuario solicita unirse a un grupo de WhatsApp que requiere aprobación, recibirás un webhook con la siguiente estructura de payload:

### Solicitud

```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"
    }
  }
}
```

### Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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

### Explicación

Enruta el evento mediante `type`, deduplícalo mediante `id` y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

## Fallo al eliminar participante

Cuando la eliminación de uno o más participantes falla o tiene éxito parcial, recibirás un webhook con la siguiente estructura de payload:

### Solicitud

```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"
  }
}
```

### Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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

### Explicación

* **type**: Siempre `whatsapp.group.participants_update` para eventos de participantes de grupos y solicitudes de unión
* **whatsappGroup**: Contiene los detalles de actualización del participante del grupo o de la solicitud de unión
  * **field**: Siempre `group_participants_update`
  * **type**: El tipo de evento del participante, como `group_participants_add`, `group_participants_remove`, `group_join_request_created` o `group_join_request_revoked`
  * **status**: El estado normalizado del evento, como `added`, `removed`, `left`, `requested`, `revoked` o `failed`
  * **groupId**: El ID del grupo de WhatsApp
  * **reason**: El motivo del evento del participante o de la solicitud de unión
  * **joinRequestId**: El ID de la solicitud de unión, incluido para eventos de solicitud de unión
  * **initiatedBy**: Indica quién inició un evento de eliminación, como `business` o `participant`
  * **recipientUserId** y **parentRecipientUserId**: IDs de usuario a nivel de empresa para el participante afectado
  * **addedParticipants**, **removedParticipants** y **failedParticipants**: Detalles a nivel de participante para actualizaciones por lotes o con resultados parciales

<br />


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