# WhatsApp group webhooks

Two webhook events report join-request activity on a [group](/docs/guides/whatsapp/groups) that requires approval. Both are the requester's own doing, so neither shows up on the response to any call you make, and a request raised and cancelled between two reads of the list leaves nothing behind. Subscribe to them and you do not have to poll.

| Event                                 | Fires when                                     |
| ------------------------------------- | ---------------------------------------------- |
| `whatsapp.group.join_request_created` | Someone opens the invite link and asks to join |
| `whatsapp.group.join_request_revoked` | They cancel that request before you decide it  |

Deciding a request fires no event, because the outcome is already on the response to your own call. Neither event is part of a message's timeline.

## Join request created

```json
{
  "type": "whatsapp.group.join_request_created",
  "timestamp": "2026-09-22T10:07:57Z",
  "data": {
    "group_id": "wag_01krdgeqd0abc5s7t44vh8rt9mg",
    "whatsapp_number_id": "wan_01krdgeqd1def5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "join_request": {
      "id": "wgj_01krdgeqcxet5s7t44vh8rt9mg",
      "bsuid": "US.1566655121691972",
      "phone_number": "+13124495648",
      "username": "john.doe"
    }
  }
}
```

`timestamp` is when the person asked to join.

## Join request revoked

```json
{
  "type": "whatsapp.group.join_request_revoked",
  "timestamp": "2026-09-22T11:12:03Z",
  "data": {
    "group_id": "wag_01krdgeqd0abc5s7t44vh8rt9mg",
    "whatsapp_number_id": "wan_01krdgeqd1def5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "join_request": {
      "id": "wgj_01krdgeqcxet5s7t44vh8rt9mg",
      "bsuid": "US.1566655121691972",
      "phone_number": "+13124495648",
      "username": "john.doe"
    }
  }
}
```

The `data` is the same as on the request it cancels, with the same `join_request.id`. `timestamp` is when the request was cancelled.

## Fields

| Field                       | Meaning                                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_id`                  | The group the person asked to join                                                                                                                                                                                        |
| `whatsapp_number_id`        | The business number that created and administers the group                                                                                                                                                                |
| `workspace_id`              | The workspace that owns the group                                                                                                                                                                                         |
| `join_request.id`           | The request. The same ID the [join-request list](/docs/guides/whatsapp/groups/management#3-let-people-into-the-group) returns and the batch approve and reject operations take, so you can decide straight from the event |
| `join_request.bsuid`        | The requester's [business-scoped user ID](/docs/guides/whatsapp/business-scoped-user-ids). Every request carries it, and it carries over to `participants` if you approve, so key your own records on it                  |
| `join_request.phone_number` | The requester's number in E.164 format, or `null` if they have not shared it with your business                                                                                                                           |
| `join_request.username`     | The requester's WhatsApp username, or `null` if they have not chosen one                                                                                                                                                  |

## Next steps

- [Managing WhatsApp groups](/docs/guides/whatsapp/groups/management#3-let-people-into-the-group): approve or reject a request
- [WhatsApp webhooks](/docs/guides/whatsapp/webhooks): the other events you can subscribe to
- [Webhooks guide](/docs/guides/webhooks): endpoints, signature verification, and retries

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)