WhatsApp Group Participants Update Webhook Examples

Participant Added

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

{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "tenantId": "tenant-id",
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "[email protected]",
    "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"
  }
}

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:

{
  "id": "evt_group_participants_124",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "tenantId": "tenant-id",
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_join_request_created",
    "status": "requested",
    "groupId": "[email protected]",
    "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"
  	}
  }
}

Participant Removal Failed

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

{
  "id": "evt_group_participants_125",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "tenantId": "tenant-id",
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "requestId": "REQ_REMOVE",
    "status": "failed",
    "groupId": "[email protected]",
    "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"
  }
}

Payload Description

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