user_joined_group

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.

The internal event name (used when subscribing webhooks in the Console) is user_joined_group.

Point a listener at your URL with EventName: "user_joined_group". To listen to a single group, add its GroupId to the body. Auth, secret and verification in Subscribing and verifying webhooks.

curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/integration/01HQ0ABCDEF1234567890XYZ/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "EventName": "user_joined_group",
    "Url": "https://myapp.com/webhooks/cativa",
    "IsActive": true
  }'

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:

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

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.

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-Idempotency-Key`	Canonical deduplication key. Identical across all retries of the same delivery.
`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.

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.

Reacting to the event

After verifying the signature, mirror the join into your external workspace. The example maps Cativa’s GroupId to a channel (Discord/Slack) and adds the member:

const CHANNEL_BY_GROUP = {
  '01HQ2GROUP1234567890XYZAB': 'discord-mentorship-channel',
};

async function onUserJoinedGroup(event) {
  const { GroupId, GroupName, User } = event;

  const channelId = CHANNEL_BY_GROUP[GroupId];
  if (!channelId) return; // group with no mirrored channel

  await chat.addMemberToChannel(channelId, {
    email: User.Email,
    displayName: User.DisplayName,
    welcome: `Welcome to ${GroupName}!`,
  });
}

user_received_badge

Fired when the user earns a badge — often the trigger that leads to a group join.

user_created

Fired when the user is created in the tenant for the first time.

Subscribing to webhooks

How to register listeners, verify HMAC and handle retries.

Webhooks (overview)

Why webhooks, delivery guarantees and payload format.

Get Started

Concepts

Guides

Webhooks

Changelog

When it fires

When it does NOT fire

Payload

Payload fields

Request headers

Use cases

Reacting to the event

user_received_badge

user_created

Subscribing to webhooks

Webhooks (overview)

​Subscribe to this event

​When it fires

​When it does NOT fire

​Payload

​Payload fields

​Request headers

​Use cases

​Reacting to the event

​Related events

user_received_badge

user_created

Subscribing to webhooks

Webhooks (overview)

Subscribe to this event

When it fires

When it does NOT fire

Payload

Payload fields

Request headers

Use cases

Reacting to the event

Related events