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 Overview
This catalog provides detailed information about each webhook event, including exact trigger conditions, related events, and practical use cases.
Challenge Events
challenge-started
Overview
Trigger Conditions
Related Events
Use Cases
When it fires: The moment a user clicks “Start Challenge” and the system creates a challenge participation record.Frequency: Once per user per challenge attemptIdempotency: Starting the same challenge again creates a new event
✅ 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
Events that commonly fire in sequence:
challenge-started (this event)action-participation (for each action completed)challenge-completion (when all actions done)reward-distribution (if rewards configured)achievement-completion (if triggers achievement)
- Send “Good luck!” email
- Track engagement metrics
- Start completion timer
- Notify team members
- Update user journey stage
challenge-completion
Overview
Trigger Conditions
Related Events
Use Cases
When it fires: When all required actions in a challenge are marked as complete.Frequency: Once per successful challenge completionIdempotency: Completing an already-completed challenge does not fire again
✅ 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
Typically followed by:
reward-distribution (immediate)achievement-completion (if applicable)streak-extended (if maintains streak)xp-gained (if XP awarded)
- Send congratulations message
- Distribute rewards
- Update completion stats
- Check achievement progress
- Trigger follow-up campaigns
Reward Events
reward-distribution
Overview
Trigger Conditions
Payload Details
Use Cases
When it fires: When the system grants rewards to a user (points, XP, items).Frequency: Can fire multiple times per trigger eventNote: This is the most data-rich webhook event
✅ 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
Contains comprehensive information:
- User details (ID, email, externalUserId)
- Points earned
- XP earned
- Reward items with metadata
- Trigger event information
- Campaign associations
- Issue gift cards
- Send reward notifications
- Update loyalty points
- Fulfill physical rewards
- Sync with CRM
reward-claim
Overview
Trigger Conditions
Use Cases
When it fires: When a user claims an available reward from their rewards list.Frequency: Once per reward claim actionDifferent from: reward-distribution (automatic) vs reward-claim (user action)
✅ 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
- Send claim confirmation
- Start fulfillment process
- Track claim rates
- Set expiration reminders
reward-redemption
Overview
Trigger Conditions
Use Cases
When it fires: When a user redeems/uses a previously claimed reward.Frequency: Once per redemptionLifecycle: Distribution → Claim → Redemption
✅ 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
- Activate voucher codes
- Track redemption rates
- Process payments
- Send redemption receipt
Commerce Events
shop-purchase
Overview
Trigger Conditions
Use Cases
When it fires: When a user spends points to purchase items from the shop.Frequency: Once per purchase transactionContains: Purchase details, points spent, items received
✅ 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
- Trigger fulfillment
- Send order confirmation
- Update inventory
- Deduct points
- Track purchase analytics
Achievement Events
achievement-completion
Overview
Trigger Conditions
Use Cases
When it fires: When a user meets all criteria for an achievement.Frequency: Once per achievement per userTypes: Can be one-time or recurring (daily, weekly, monthly)
✅ 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
- Issue badges
- Send achievement notification
- Unlock exclusive rewards
- Update user profile
- Trigger next achievement tier
Social Events
post-like
Overview
Trigger Conditions
Use Cases
When it fires: When a user likes a community post.Frequency: Once per like actionReversible: Unliking does not fire an “unlike” event
✅ Fires when:
- User clicks like button
- Like record created
- Post is active
❌ Does NOT fire when:
- Already liked
- Post archived
- User lacks permission
- Track engagement
- Notify post author
- Update engagement achievements
- Calculate trending posts
Overview
Trigger Conditions
Use Cases
When it fires: When a user comments on a post.Frequency: Once per commentContains: Post ID and comment ID
✅ Fires when:
- Comment submitted
- Comment passes moderation
- Comment record created
❌ Does NOT fire when:
- Comment fails moderation
- Comments disabled
- User banned from commenting
- Notify participants
- Track discussions
- Trigger moderation
- Email digest updates
Gamification Events
streak-extended
Overview
Trigger Conditions
Use Cases
When it fires: When a user maintains their activity streak.Frequency: Once per day when streak conditions metReset: Streak resets if user misses a day
✅ 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
- Update streak counter
- Award streak achievements
- Send streak reminders
- Unlock streak rewards
- Track retention metrics
User Events
auth.email
Overview
Trigger Conditions
Use Cases
When it fires: When a new user account is created via email authentication.Frequency: Once per user creationContains: Basic user information
✅ 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
- Send welcome email
- Create CRM contact
- Award signup bonus
- Track acquisition
- Notify sales team
organisation.invite-admin-user
Overview
Trigger Conditions
Use Cases
When it fires: When an admin user is invited to an organization.Frequency: Once per invitationScope: Organization-level administrative event
✅ Fires when:
- Admin invitation sent
- Invitation record created
- Email dispatched
❌ Does NOT fire when:
- Regular user invited
- Invitation fails
- User already admin
- Send invitation email
- Audit admin access
- Log security events
- Track organization growth
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)
