> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# user_joined_group

> Fired when a user joins a group in the community — voluntarily, by invite, by badge automation or by bulk import.

This event fires **every time a user becomes a member of a group**, regardless of the path: they joined themselves, an admin added them, they got access because they earned a badge, or they came in through a bulk import.

<Note>
  The internal event name (used when subscribing webhooks in the Console) is `user_joined_group`.
</Note>

## When it fires

* User joins a public group through the community UI
* User accepts an invite to a private group
* Admin adds the user to the group manually
* Badge automation grants access to the group (group restricted to a specific badge)
* Bulk operation includes the user in the group
* You add the user to the group via API

## When it does NOT fire

* User leaves the group (this is a separate event, not yet exposed via webhook)
* A pending join request to a private group that's awaiting admin approval (it only fires after the admin approves)
* Re-join — if the user is already a member, nothing happens
* User not found while enriching the payload (delivery is skipped)
* Operation fails validation (group doesn't exist, user is banned, etc.)

## Payload

The payload is serialized in **PascalCase** and delivered in the body of the `POST` with `Content-Type: application/json`:

```json theme={null}
{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "GroupId": "01HQ2GROUP1234567890XYZAB",
  "GroupName": "Premium Mentorship",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "mary@example.com",
    "FirstName": "Mary",
    "LastName": "Smith",
    "DisplayName": "Mary Smith",
    "Username": "mary.smith",
    "PhoneNumber": "+15551234567",
    "CreatedAt": "2026-04-12T14:32:01Z",
    "BadgeId": "01HQ4ABCDEF1234567890XYZ",
    "Badges": [
      "01HQ4ABCDEF1234567890XYZ"
    ]
  },
  "JoinedAt": "2026-05-08T14:32:01Z"
}
```

### Payload fields

| Field              | Type         | Description                                                                                                          |
| ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `CustomerId`       | GUID         | ID of the tenant that emitted the event. Use it to route when your endpoint receives webhooks from multiple tenants. |
| `GroupId`          | GUID         | ID of the group the user joined.                                                                                     |
| `GroupName`        | string       | Name of the group at the moment of the event (snapshot — does not change if the name is edited later).               |
| `User.Id`          | GUID         | ID of the user who joined the group.                                                                                 |
| `User.Email`       | string       | User email.                                                                                                          |
| `User.FirstName`   | string       | First name.                                                                                                          |
| `User.LastName`    | string       | Last name.                                                                                                           |
| `User.DisplayName` | string       | Display name.                                                                                                        |
| `User.Username`    | string       | Username.                                                                                                            |
| `User.PhoneNumber` | string       | Phone, when provided.                                                                                                |
| `User.CreatedAt`   | ISO 8601     | When the user was created in the tenant.                                                                             |
| `User.BadgeId`     | GUID \| null | User's primary badge.                                                                                                |
| `User.Badges`      | GUID\[]      | Full list of badges the user holds at the time of the event.                                                         |
| `JoinedAt`         | ISO 8601     | When the join happened.                                                                                              |

<Note>
  The payload does **not** explicitly indicate the channel through which the user joined (manual, badge, invite, bulk). If you need to tell them apart, use listener conditions in the Console — for instance, register one listener per `GroupId`, or filter on `User.Badges` to detect joins driven by badge automations.
</Note>

## Request headers

| Header                   | Description                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `X-Cativa-Signature`     | HMAC-SHA256 signature of the delivery, in the format `t=<unixTs>,v1=<hex>`. **Verify it before processing the event.** |
| `X-Cativa-Execution-Id`  | Unique ID of this event. Stable across retries — use it as your idempotency key.                                       |
| `X-Cativa-Automation-Id` | ID of the listener configured in the Console (same value across all deliveries from the same subscription).            |

The full explanation of how to verify `X-Cativa-Signature`, handle retries and ensure idempotency (with examples in Node, Python, Go and C#) lives in [Subscribing and verifying webhooks](/en/webhooks/subscribing-and-verifying).

## Use cases

* **Sync with Discord/Slack** — when someone joins the "Premium Mentorship" group, automatically add them to the matching channel in your external workspace.
* **Send a contextual email** — fire a welcome message specific to that group, with onboarding material, links and next steps.
* **Update segmentation** — record the join in your CRM/marketing automation so later campaigns recognize the user as a member of the group.

## Related events

<CardGroup cols={2}>
  <Card title="user_received_badge" icon="shield-check" href="/en/webhooks/events/user-received-badge">
    Fired when the user earns a badge — often the trigger that leads to a group join.
  </Card>

  <Card title="user_created" icon="user-plus" href="/en/webhooks/events/user-created">
    Fired when the user is created in the tenant for the first time.
  </Card>

  <Card title="Subscribing to webhooks" icon="webhook" href="/en/webhooks/subscribing-and-verifying">
    How to register listeners, verify HMAC and handle retries.
  </Card>

  <Card title="Webhooks (overview)" icon="rectangle-history" href="/en/concepts/webhooks">
    Why webhooks, delivery guarantees and payload format.
  </Card>
</CardGroup>