Group Webhook events

This section covers event callbacks related to Group. To receive notifications of group metadata changes, enable the following fields in your WebHook subscription (each corresponds to the event types in the subsections below):group_lifecycle_update(group creation / deletion);group_participants_update(group member changes: join via invite link / request to join / cancel request / join request approved / removed / leave voluntarily);group_settings_update(group settings: topic / description / profile picture update);group_status_update(group suspended / suspension cleared). The events in this section all use the InnoPaas public envelope (id、type、eventTime、body) and the 5 InnoPaas event types in this section:whatsapp_group_lifecycle_update、whatsapp_group_participants_update、whatsapp_group_settings_update、whatsapp_group_status_update、whatsapp_group_message_status_updated。

The public fields below apply to all events in this section (consistent with the common parameters above; only fields unique to group events or easily confused are listed here):

Field	Data type	Required	Description
group_id	String	Yes	Group ID, the group_id returned by the Groups API
type	String	Yes	Sub-event type, see each subsection
timestamp	String	Yes	Event trigger time, UTC format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
request_id	String	No	Request ID, used for troubleshooting and correlating API calls

Group lifecycle (whatsapp_group_lifecycle_update)

This event is triggered when a group is created or deleted:whatsapp_group_lifecycle_update, corresponding subscription field group_lifecycle_update。type The fields distinguish sub-events:group_create(success / failure),group_delete(success / failure).

Field	Data type	Required	Description
group_id	String	Yes	Group ID
type	String	Yes	Sub-event type, possible values:group_create、group_delete
subject	String	No	Group topic;returned when type=group_createis returned;returned when type=group_createTopic used on failure
invite_link	String	No	Group invite link,returned when type=group_createand returned on success
join_approval_mode	String	No	Group join approval mode:auto_approve(no approval required) /approval_required(approval required),returned when type=group_createand returned on success
request_id	String	No	Request ID
timestamp	String	Yes	Event trigger time
errors	Array	No	Error array returned on failure (structure same as the errors in the upstream message)

group_create success: Response example

{
    "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22",
    "type": "whatsapp_group_lifecycle_update",
    "eventTime": "2026-09-03T08:00:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_create",
        "subject": "test invite link",
        "invite_link": "https://chat.whatsapp.com/LINK_ID",
        "join_approval_mode": "auto_approve",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:00:00.000Z"
    }
}

group_create failed: Response example

{
    "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22",
    "type": "whatsapp_group_lifecycle_update",
    "eventTime": "2026-09-03T08:00:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_create",
        "subject": "GROUP_SUBJECT",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:00:00.000Z",
        "errors": [
            {
                "code": "ERROR_CODE",
                "message": "ERROR_MESSAGE",
                "title": "ERROR_TITLE",
                "error_data": {
                    "details": "ERROR_DETAILS"
                }
            }
        ]
    }
}

group_delete failed: Response example

{
    "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22",
    "type": "whatsapp_group_lifecycle_update",
    "eventTime": "2026-09-03T08:00:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_delete",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:00:00.000Z",
        "errors": [
            {
                "code": "ERROR_CODE",
                "message": "ERROR_MESSAGE",
                "title": "ERROR_TITLE",
                "error_data": {
                    "details": "ERROR_DETAILS"
                }
            }
        ]
    }
}

group_delete succeeded JSON payload example: data to be added (the successful create/delete payloads are missing key fields for verification; they will be completed after alignment with upstream; see above for the successful create payload).

Group participant changes (whatsapp_group_participants_update)

This event is triggered when group members undergo the following changes:whatsapp_group_participants_update, corresponding subscription field group_participants_updateCommon sub-events: users join the group via invite link (reason=invite_link); users submit a join request (reason=join_request,group_request_type=group_join_request_created); users revoke a join request (group_request_type=group_join_request_revoked); one or more join requests approved (reason=invite_link,type=group_participants_add,added_participants[]); remove group members:type=group_participants_remove, may partially succeed / fully succeed / fully fail; group members leave voluntarily:initiated_by and removed_participants[].wa_id point to the departing member.

Field	Data type	Required	Description
group_id	String	Yes	Group ID
type	String	Yes	Sub-event type, possible values:group_participants_add、group_participants_removeetc.
reason	String	No	Trigger reason, for exampleinvite_link(join via invite link / join request approved)
group_request_type	String	No	Join request type:group_join_request_created(requested),group_join_request_revoked(revoked)
added_participants	Array	No	List of added members, each item{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}
removed_participants	Array	No	List of removed members, each item{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}; when leaving voluntarilyinitiated_byand thewa_idboth point to the departing member
initiated_by	String	No	WhatsApp user ID that initiated this change (removal / leave scenario)
request_id	String	No	Request ID
timestamp	String	Yes	Event trigger time
errors	Array	No	Error array returned on failure

Join request approved (bulk multiple members): Response example

{
    "id": "7a2e3b55-2c5c-4c2f-ae3d-8b9c2a1f4d33",
    "type": "whatsapp_group_participants_update",
    "eventTime": "2026-09-03T08:10:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_participants_add",
        "reason": "invite_link",
        "timestamp": 1783558600,
        "added_participants": [
            {
                "input": "WHATSAPP_USER_PHONE_NUMBER",
                "wa_id": "WHATSAPP_USER_ID"
            }
        ]
    }
}

JSON payload example for other sub-events (users joining via invite link, join/cancel request, member removal success / partial failure / failure, member leaving voluntarily): data to be added (type The values and field order follow the mirrored source documentation; the complete JSON will be added after alignment with upstream; the trigger conditions and field definitions are based on the table above).

Group settings update (whatsapp_group_settings_update)

This event is triggered when group settings (topic / description / profile picture) are updated:whatsapp_group_settings_update, corresponding subscription field group_settings_update。update_successful This field indicates whether this update was successful; on failure it is accompanied by the errors array. The overall update may succeed / partially fail / completely fail.

Field	Data type	Required	Description
group_id	String	Yes	Group ID
type	String	Yes	Fixed value:group_settings_update
profile_picture	Object	No	Profile picture update result:mime_type(e.g. image/jpeg),sha256(returned on success),update_successful(Boolean),errors(returned only on failure)
group_subject	Object	No	Topic update result:text、update_successful(Boolean),errors(returned only on failure)
group_description	Object	No	Description update result:text、update_successful(Boolean),errors(returned only on failure)
request_id	String	No	Request ID
timestamp	String	Yes	Event trigger time
errors	Array	No	Top-level error array returned when the update overall fails / partially fails

All successful: Response example

{
    "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44",
    "type": "whatsapp_group_settings_update",
    "eventTime": "2026-09-03T08:20:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_settings_update",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:20:00.000Z",
        "profile_picture": {
            "mime_type": "image/jpeg",
            "update_successful": true,
            "sha256": "PHOTO_HASH"
        },
        "group_subject": {
            "text": "Test Subject",
            "update_successful": true
        },
        "group_description": {
            "text": "Test Description",
            "update_successful": true
        }
    }
}

Partial failure: Response example

{
    "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44",
    "type": "whatsapp_group_settings_update",
    "eventTime": "2026-09-03T08:20:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_settings_update",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:20:00.000Z",
        "profile_picture": {
            "mime_type": "image/jpeg",
            "update_successful": true,
            "sha256": "PHOTO_HASH"
        },
        "group_subject": {
            "text": "Test Subject",
            "update_successful": false,
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        },
        "group_description": {
            "text": "Test Description",
            "update_successful": false,
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        },
        "errors": [
            {
                "code": "ERROR_CODE",
                "message": "ERROR_MESSAGE",
                "error_data": {
                    "details": "ERROR_DETAILS"
                }
            }
        ]
    }
}

Complete failure: Response example

{
    "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44",
    "type": "whatsapp_group_settings_update",
    "eventTime": "2026-09-03T08:20:00.000Z",
    "body": {
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "type": "group_settings_update",
        "request_id": "REQUEST_ID",
        "timestamp": "2026-09-03T08:20:00.000Z",
        "profile_picture": {
            "mime_type": "image/jpeg",
            "sha256": "PHOTO_HASH",
            "update_successful": false,
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        },
        "group_subject": {
            "text": "Test Subject",
            "update_successful": false
        }
    }
}

Group status changes (whatsapp_group_status_update)

This event is triggered when a group you manage is suspended or unsuspended:whatsapp_group_status_update, corresponding subscription field group_status_update。type The fields distinguish sub-events:group_suspend(suspended),group_suspend_cleared(suspension cleared).

Field	Data type	Required	Description
group_id	String	Yes	Group ID
type	String	Yes	Sub-event type, possible values:group_suspend、group_suspend_cleared
timestamp	String	Yes	Event trigger time

group_suspend: Response example

{
    "id": "9c4a5d77-4e7e-4e41-c05f-ad1e4c3b6f55",
    "type": "whatsapp_group_status_update",
    "eventTime": "2026-09-03T08:30:00.000Z",
    "body": {
        "type": "group_suspend",
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "timestamp": "2026-09-03T08:30:00.000Z"
    }
}

group_suspend_cleared: Response example

{
    "id": "9c4a5d77-4e7e-4e41-c05f-ad1e4c3b6f55",
    "type": "whatsapp_group_status_update",
    "eventTime": "2026-09-03T08:35:00.000Z",
    "body": {
        "type": "group_suspend_cleared",
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "timestamp": "2026-09-03T08:35:00.000Z"
    }
}

Group message status (whatsapp_group_message_status_updated)

When sending a group message, this event is triggered according to the message lifecycle (sent / send failed / delivered / read):whatsapp_group_message_status_updated, corresponding to whatsapp_message_status_updated under the event recipient_type=group subset. This event is also used foraggregationreceipts: receipts of the same message and same status type within a close time window are merged; each receipt only relates tosingle message + single group + single status type. Billing categories are group_marketing / group_utility / group_service,PRICING_MODEL is PMP,IS_BILLABLE indicates whether it is billable.

Note: inbound receipts for receiving group user messages still go through whatsapp_mo_message_received, only in message object does it additionally carry the group_id field, and from points to the sending participant.

Field	Data type	Required	Description
id	String	Yes	Message Id
accountName	String	Yes	API account
wabaId	String	Yes	Waba Id
wamid	String	Yes	Group message ID
status	String	Yes	Sending status:sent、failed、delivered、read
recipient_id	String	Yes	Group ID (distinguished from one-to-one receiptssendPhone)
recipient_type	String	Yes	Fixed value:group
recipient_participant_id	String	No	The WhatsApp number of the group member corresponding to a single receipt (when aggregated, the same receipt may include multiple members; see the note in the field table for recipient_participant_ids)
conversation	JSON	No	Conversation info, present when status=delivered; includesid、initiateType、expireAt
errorData	JSON	No	Error info, present when status=failed; includeserrorCode、errorMessage
billable	Boolean	Yes	Whether billable: true / false
category	String	Yes	Group message type:group_marketing、group_utility、group_service
price	String	Yes	Unit price, keep 5 decimal places
currency	String	Yes	Currency
pricing_model	String	No	Fixed value:PMP
is_billable	Boolean	No	Whether billable (synonymous withbillableand the naming follows the upstream field)
conversation_category	String	No	Billing category (withcategoryand the naming follows the upstream field)
uid	String	No	customer batch number

sent: Response example

{
    "id": "ad5b6e88-5f8f-4f52-d160-be2f5d4c7066",
    "type": "whatsapp_group_message_status_updated",
    "eventTime": "2026-09-03T08:40:00.000Z",
    "body": {
        "id": "356139161272397824",
        "accountName": "IW123456",
        "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "wamid": "wamid.BgNODYxN...",
        "status": "sent",
        "recipient_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "recipient_type": "group",
        "recipient_participant_id": "WHATSAPP_USER_PHONE_NUMBER",
        "uid": "2002302023002010121",
        "currency": "USD"
    }
}

failed: Response example

{
    "id": "ad5b6e88-5f8f-4f52-d160-be2f5d4c7066",
    "type": "whatsapp_group_message_status_updated",
    "eventTime": "2026-09-03T08:40:00.000Z",
    "body": {
        "id": "356139161272397824",
        "accountName": "IW123456",
        "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "wamid": "wamid.BgNODYxN...",
        "status": "failed",
        "recipient_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "recipient_type": "group",
        "recipient_participant_id": "WHATSAPP_USER_PHONE_NUMBER",
        "uid": "2002302023002010121",
        "currency": "USD",
        "errorData": {
            "errorCode": "ERROR_CODE",
            "errorMessage": "ERROR_MESSAGE"
        }
    }
}

JSON payload example for aggregated delivered / read receipts for group messages: data to be added (statuses[] array, billing category group_marketing / group_utility / group_service、PRICING_MODEL=PMP、IS_BILLABLE etc. The field arrangement follows the mirrored source documentation; the aggregation rules for multiple participants for one message or multiple messages for one participant are described in the table; the complete JSON will be added after alignment with upstream).

Receiving group user message (inbound): Response example

{
    "id": "be6c7f99-6a90-5063-e271-cf3f6e5d8177",
    "type": "whatsapp_mo_message_received",
    "eventTime": "2026-09-03T08:50:00.000Z",
    "body": {
        "id": "63f5d602367ea403f8175a6c",
        "accountName": "IW123456",
        "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "wamid": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
        "from": "WHATSAPP_USER_PHONE_NUMBER",
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "customerProfile": {
            "name": "Jack"
        },
        "to": "BUSINESS-PHONE-NUMBER",
        "sendTime": "2026-09-03T08:50:00.000Z",
        "type": "text",
        "text": {
            "body": "MESSAGE_BODY"
        }
    }
}

Receiving unsupported group message (inbound): Response example

{
    "id": "be6c7f99-6a90-5063-e271-cf3f6e5d8177",
    "type": "whatsapp_mo_message_received",
    "eventTime": "2026-09-03T08:50:00.000Z",
    "body": {
        "id": "63f5d602367ea403f8175a6c",
        "accountName": "IW123456",
        "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "wamid": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
        "from": "WHATSAPP_USER_PHONE_NUMBER",
        "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
        "customerProfile": {
            "name": "Jack"
        },
        "to": "BUSINESS-PHONE-NUMBER",
        "sendTime": "2026-09-03T08:50:00.000Z",
        "type": "unknown",
        "errors": [
            {
                "code": 130501,
                "details": "Group message types are not currently supported",
                "title": "Unsupported group message type"
            }
        ]
    }