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

Para consultar el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.

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

Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.

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

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

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

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

Primeros pasos

Guías

Endpoints

Webhooks

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

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Participante añadido

Solicitud

Respuesta

Explicación

Solicitud de unión creada

Solicitud

Respuesta

Explicación

Fallo al eliminar participante

Solicitud

Respuesta

Explicación

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Participante añadido

​Solicitud

​Respuesta

​Explicación

​Solicitud de unión creada

​Solicitud

​Respuesta

​Explicación

​Fallo al eliminar participante

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Participante añadido

Solicitud

Respuesta

Explicación

Solicitud de unión creada

Solicitud

Respuesta

Explicación

Fallo al eliminar participante

Solicitud

Respuesta

Explicación