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

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

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

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)

Use Cases

• Send “Good luck!” email
• Track engagement metrics
• Start completion timer
• Notify team members
• Update user journey stage

challenge-completion

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

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

Related Events

Typically followed by:

• reward-distribution (immediate)
• achievement-completion (if applicable)
• streak-extended (if maintains streak)
• xp-gained (if XP awarded)

Use Cases

• Send congratulations message
• Distribute rewards
• Update completion stats
• Check achievement progress
• Trigger follow-up campaigns

Reward Events

reward-distribution

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

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

Payload Details

Contains comprehensive information:

• User details (ID, email, externalUserId)
• Points earned
• XP earned
• Reward items with metadata
• Trigger event information
• Campaign associations

Use Cases

• Issue gift cards
• Send reward notifications
• Update loyalty points
• Fulfill physical rewards
• Sync with CRM

reward-claim

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)

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

Use Cases

• Send claim confirmation
• Start fulfillment process
• Track claim rates
• Set expiration reminders

reward-redemption

Overview

When it fires: When a user redeems/uses a previously claimed reward.

Frequency: Once per redemption

Lifecycle: Distribution → Claim → Redemption

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

Use Cases

• Activate voucher codes
• Track redemption rates
• Process payments
• Send redemption receipt

Commerce Events

shop-purchase

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

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

Use Cases

• Trigger fulfillment
• Send order confirmation
• Update inventory
• Deduct points
• Track purchase analytics

Achievement Events

achievement-completion

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)

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

Use Cases

• Issue badges
• Send achievement notification
• Unlock exclusive rewards
• Update user profile
• Trigger next achievement tier

Social Events

post-like

Overview

When it fires: When a user likes a community post.

Frequency: Once per like action

Reversible: Unliking does not fire an “unlike” event

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

Use Cases

• Track engagement
• Notify post author
• Update engagement achievements
• Calculate trending posts

post-comment

Overview

When it fires: When a user comments on a post.

Frequency: Once per comment

Contains: Post ID and comment ID

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

Use Cases

• Notify participants
• Track discussions
• Trigger moderation
• Email digest updates

Gamification Events

streak-extended

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

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

Use Cases

• Update streak counter
• Award streak achievements
• Send streak reminders
• Unlock streak rewards
• Track retention metrics

User Events

auth.email

Overview

When it fires: When a new user account is created via email authentication.

Frequency: Once per user creation

Contains: Basic user information

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

Use Cases

• Send welcome email
• Create CRM contact
• Award signup bonus
• Track acquisition
• Notify sales team

organisation.invite-admin-user

Overview

When it fires: When an admin user is invited to an organization.

Frequency: Once per invitation

Scope: Organization-level administrative event

Trigger Conditions

✅ Fires when:

• Admin invitation sent
• Invitation record created
• Email dispatched

❌ Does NOT fire when:

• Regular user invited
• Invitation fails
• User already admin

Use Cases

• 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)