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

# Event Catalog

> Detailed catalog of webhook events with trigger conditions and use cases

## Event Catalog Overview

This catalog provides detailed information about each webhook event, including exact trigger conditions, related events, and practical use cases.

## Challenge Events

### challenge-started

<Tabs>
  <Tab title="Overview">
    **When it fires**: The moment a user clicks "Start Challenge" and the system creates a challenge participation record.

    **Frequency**: Once per user per challenge attempt

    **Idempotency**: Starting the same challenge again creates a new event
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * User clicks "Start Challenge" button
    * API call to `/challenges/{id}/start` succeeds
    * Challenge participation record is created

    ❌ Does NOT fire when:

    * User views challenge details
    * Challenge is already completed
    * User lacks permission to start challenge
  </Tab>

  <Tab title="Related Events">
    Events that commonly fire in sequence:

    1. `challenge-started` (this event)
    2. `action-participation` (for each action completed)
    3. `challenge-completion` (when all actions done)
    4. `reward-distribution` (if rewards configured)
    5. `achievement-completion` (if triggers achievement)
  </Tab>

  <Tab title="Use Cases">
    * Send "Good luck!" email
    * Track engagement metrics
    * Start completion timer
    * Notify team members
    * Update user journey stage
  </Tab>
</Tabs>

### challenge-completion

<Tabs>
  <Tab title="Overview">
    **When it fires**: When all required actions in a challenge are marked as complete.

    **Frequency**: Once per successful challenge completion

    **Idempotency**: Completing an already-completed challenge does not fire again
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Last action in challenge is completed
    * All required actions have passing scores
    * Challenge completion record is created

    ❌ Does NOT fire when:

    * Partial challenge completion
    * Challenge expired before completion
    * User fails required actions
  </Tab>

  <Tab title="Related Events">
    Typically followed by:

    * `reward-distribution` (immediate)
    * `achievement-completion` (if applicable)
    * `streak-extended` (if maintains streak)
    * `xp-gained` (if XP awarded)
  </Tab>

  <Tab title="Use Cases">
    * Send congratulations message
    * Distribute rewards
    * Update completion stats
    * Check achievement progress
    * Trigger follow-up campaigns
  </Tab>
</Tabs>

## Reward Events

### reward-distribution

<Tabs>
  <Tab title="Overview">
    **When it fires**: When the system grants rewards to a user (points, XP, items).

    **Frequency**: Can fire multiple times per trigger event

    **Note**: This is the most data-rich webhook event
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Challenge completion triggers reward rules
    * Achievement unlocked with rewards
    * Manual reward distribution by admin
    * Scheduled reward distribution (e.g., leaderboard)

    ❌ Does NOT fire when:

    * User purchases from shop
    * Reward claimed but not distributed
    * Distribution rules not met
  </Tab>

  <Tab title="Payload Details">
    Contains comprehensive information:

    * User details (ID, email, externalUserId)
    * Points earned
    * XP earned
    * Reward items with metadata
    * Trigger event information
    * Campaign associations
  </Tab>

  <Tab title="Use Cases">
    * Issue gift cards
    * Send reward notifications
    * Update loyalty points
    * Fulfill physical rewards
    * Sync with CRM
  </Tab>
</Tabs>

### reward-claim

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user claims an available reward from their rewards list.

    **Frequency**: Once per reward claim action

    **Different from**: `reward-distribution` (automatic) vs `reward-claim` (user action)
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * User clicks "Claim Reward"
    * Reward is available and not expired
    * User has sufficient permissions

    ❌ Does NOT fire when:

    * Reward auto-distributed
    * Reward expired
    * Already claimed
  </Tab>

  <Tab title="Use Cases">
    * Send claim confirmation
    * Start fulfillment process
    * Track claim rates
    * Set expiration reminders
  </Tab>
</Tabs>

### reward-redemption

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user redeems/uses a previously claimed reward.

    **Frequency**: Once per redemption

    **Lifecycle**: Distribution → Claim → Redemption
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * User clicks "Redeem" on claimed reward
    * Redemption code is used
    * Admin marks as redeemed

    ❌ Does NOT fire when:

    * Reward claimed but not redeemed
    * Redemption fails validation
    * Reward expired
  </Tab>

  <Tab title="Use Cases">
    * Activate voucher codes
    * Track redemption rates
    * Process payments
    * Send redemption receipt
  </Tab>
</Tabs>

## Commerce Events

### shop-purchase

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user spends points to purchase items from the shop.

    **Frequency**: Once per purchase transaction

    **Contains**: Purchase details, points spent, items received
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Purchase transaction completes
    * User has sufficient points
    * Item is in stock

    ❌ Does NOT fire when:

    * Insufficient points
    * Item out of stock
    * Purchase cancelled
  </Tab>

  <Tab title="Use Cases">
    * Trigger fulfillment
    * Send order confirmation
    * Update inventory
    * Deduct points
    * Track purchase analytics
  </Tab>
</Tabs>

## Achievement Events

### achievement-completion

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user meets all criteria for an achievement.

    **Frequency**: Once per achievement per user

    **Types**: Can be one-time or recurring (daily, weekly, monthly)
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Achievement criteria met
    * Progress reaches 100%
    * Recurring achievement resets and completes

    ❌ Does NOT fire when:

    * Partial progress made
    * Already completed (non-recurring)
    * Achievement disabled
  </Tab>

  <Tab title="Use Cases">
    * Issue badges
    * Send achievement notification
    * Unlock exclusive rewards
    * Update user profile
    * Trigger next achievement tier
  </Tab>
</Tabs>

## Social Events

### post-like

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user likes a community post.

    **Frequency**: Once per like action

    **Reversible**: Unliking does not fire an "unlike" event
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * User clicks like button
    * Like record created
    * Post is active

    ❌ Does NOT fire when:

    * Already liked
    * Post archived
    * User lacks permission
  </Tab>

  <Tab title="Use Cases">
    * Track engagement
    * Notify post author
    * Update engagement achievements
    * Calculate trending posts
  </Tab>
</Tabs>

### post-comment

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user comments on a post.

    **Frequency**: Once per comment

    **Contains**: Post ID and comment ID
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Comment submitted
    * Comment passes moderation
    * Comment record created

    ❌ Does NOT fire when:

    * Comment fails moderation
    * Comments disabled
    * User banned from commenting
  </Tab>

  <Tab title="Use Cases">
    * Notify participants
    * Track discussions
    * Trigger moderation
    * Email digest updates
  </Tab>
</Tabs>

## Gamification Events

### streak-extended

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a user maintains their activity streak.

    **Frequency**: Once per day when streak conditions met

    **Reset**: Streak resets if user misses a day
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Daily activity requirement met
    * Streak counter increments
    * Within streak time window

    ❌ Does NOT fire when:

    * Activity already recorded today
    * Streak broken (missed day)
    * Streak feature disabled
  </Tab>

  <Tab title="Use Cases">
    * Update streak counter
    * Award streak achievements
    * Send streak reminders
    * Unlock streak rewards
    * Track retention metrics
  </Tab>
</Tabs>

## User Events

### auth.email

<Tabs>
  <Tab title="Overview">
    **When it fires**: When a new user account is created via email authentication.

    **Frequency**: Once per user creation

    **Contains**: Basic user information
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Email signup completed
    * User record created
    * Email verified (if required)

    ❌ Does NOT fire when:

    * Social login used
    * User already exists
    * Signup fails validation
  </Tab>

  <Tab title="Use Cases">
    * Send welcome email
    * Create CRM contact
    * Award signup bonus
    * Track acquisition
    * Notify sales team
  </Tab>
</Tabs>

### organisation.invite-admin-user

<Tabs>
  <Tab title="Overview">
    **When it fires**: When an admin user is invited to an organization.

    **Frequency**: Once per invitation

    **Scope**: Organization-level administrative event
  </Tab>

  <Tab title="Trigger Conditions">
    ✅ Fires when:

    * Admin invitation sent
    * Invitation record created
    * Email dispatched

    ❌ Does NOT fire when:

    * Regular user invited
    * Invitation fails
    * User already admin
  </Tab>

  <Tab title="Use Cases">
    * Send invitation email
    * Audit admin access
    * Log security events
    * Track organization growth
  </Tab>
</Tabs>

## Event Chains

Common event sequences you'll encounter:

### Challenge → Reward Flow

```
1. challenge-started
2. challenge-completion
3. reward-distribution
4. achievement-completion (if applicable)
5. streak-extended (if maintains streak)
```

### Shop Purchase Flow

```
1. shop-purchase
2. reward-distribution (item granted)
3. achievement-completion (shopping achievement)
```

### Social Engagement Flow

```
1. post-like or post-comment
2. achievement-completion (engagement achievement)
3. reward-distribution (if rewards configured)
```