WhatsApp Group Participants Update Webhook Examples

For the exhaustive schema-derived catalog, see all examples.

What it is

Handle WhatsApp group participant and join-request updates.

Before you begin

Create a public HTTPS endpoint in your application.
Configure a YCloud webhook endpoint for the event types you need.
Store the endpoint signing secret securely.
Make event processing idempotent.

How it works

YCloud sends an HTTP POST request when the event occurs. Verify the signature, durably record the event, return a 2xx response, and process slow work asynchronously.

Request

The scenarios below show requests delivered to your webhook URL. Treat the event id as the delivery identifier and use type to route the payload.

Response

Return a 2xx status after accepting the event.

HTTP/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

Participant Added

When a participant is added to a WhatsApp group, you will receive a webhook with the following payload structure:

Request

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

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Join Request Created

When a user requests to join a WhatsApp group that requires approval, you will receive a webhook with the following payload structure:

Request

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

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Participant Removal Failed

When removing one or more participants fails or partially succeeds, you will receive a webhook with the following payload structure:

Request

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

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

type: Always whatsapp.group.participants_update for group participant and join request events
whatsappGroup: Contains the group participant or join request update details
- field: Always group_participants_update
- type: The participant event type, such as group_participants_add, group_participants_remove, group_join_request_created, or group_join_request_revoked
- status: The normalized event status, such as added, removed, left, requested, revoked, or failed
- groupId: The WhatsApp group ID
- reason: The reason for the participant or join request event
- joinRequestId: The join request ID, included for join request events
- initiatedBy: Indicates who initiated a removal event, such as business or participant
- recipientUserId and parentRecipientUserId: Business-scoped user IDs for the affected participant
- addedParticipants, removedParticipants, and failedParticipants: Participant-level details for batch or partial-result updates

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Group Participants Update Webhook Examples

What it is

Before you begin

How it works

Request

Response

Participant Added

Request

Response

Explanation

Join Request Created

Request

Response

Explanation

Participant Removal Failed

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Participant Added

​Request

​Response

​Explanation

​Join Request Created

​Request

​Response

​Explanation

​Participant Removal Failed

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Participant Added

Request

Response

Explanation

Join Request Created

Request

Response

Explanation

Participant Removal Failed

Request

Response

Explanation