Skip to main content
Version: Next

Event Types Reference

This page provides a comprehensive reference of all webhook event types available in the Beedeez platform. Each event type represents a specific action or state change that can trigger a webhook notification.

Currently Supported Events​

Beedeez currently supports webhook notifications for certificate-related events. Additional event types will be added in future releases.

Certificate Events​

certificate_completed​

Triggered when a user successfully completes a certificate (badge) in the platform.

When This Event Fires:

  • User completes all requirements for a certificate
  • Certificate is automatically awarded to the user
  • Certificate is manually awarded by an administrator

Payload Contains:

  • Complete certificate (badge) details
  • User information
  • Completion date
  • Validating lesson activities
  • Expiration date (if applicable)

Use Cases:

  • Notify HR systems of employee certifications
  • Update external learning records
  • Trigger reward or recognition workflows
  • Generate compliance reports

Example Scenario:

1. User completes all lessons in a "Safety Training" track
2. System awards "Safety Certified" badge to user
3. Webhook fires with certificate_completed event
4. Your system receives notification and updates employee records

certificate_expired​

Triggered when a certificate expires due to its validity period ending.

When This Event Fires:

  • Certificate reaches its expiration date
  • System processes expired certificates (typically via scheduled job)
  • Expiry reminder email is sent to the user

Payload Contains:

  • Complete certificate (badge) details
  • User information
  • Original completion date
  • Expiration date
  • Badge status

Use Cases:

  • Notify users to renew certifications
  • Update compliance tracking systems
  • Trigger re-certification workflows
  • Alert managers of expired team certifications

Example Scenario:

1. User completed "First Aid Certification" 1 year ago
2. Certificate has 365-day validity period
3. System detects certificate has expired
4. Webhook fires with certificate_expired event
5. Your system triggers re-certification notification

Event Subscription​

When configuring a webhook endpoint, you can subscribe to one or multiple event types. Each webhook endpoint can have its own event subscription list.

Example Configuration:

{
    "name": "Certificate Notifications",
    "url": "https://api.yourcompany.com/webhooks/certificates",
    "eventTypes": ["certificate_completed", "certificate_expired"]
}

Event Filtering​

Webhooks are filtered at the organization level:

  1. Organization Check: System checks if the organization has webhook endpoints configured
  2. Event Type Match: Only endpoints subscribed to the specific event type are triggered
  3. Enabled Status: Only enabled endpoints receive notifications
  4. Delivery: Webhook notification is sent to matching endpoints

Filtering Logic:

// Pseudo-code showing filtering logic
const endpoints = memberConfig.webHookConfig.endpoints.filter((endpoint) => {
    return endpoint.enabled && endpoint.eventTypes.includes(eventType);
});

Event Payload Structure​

All webhook events follow a consistent payload structure. The exact fields depend on the event type, but generally include:

Common Fields​

  • Event Metadata: Information about the event itself
  • Organization Data: Owner/organization identifiers
  • Entity Data: The primary entity related to the event (certificate, user, lesson, etc.)
  • Related Entities: Associated data (user info, lesson details, etc.)

Certificate Event Payload​

For certificate events (certificate_completed and certificate_expired), the payload contains the complete BadgeUser document, which includes:

{
    "_id": "badge_user_id",
    "_userId": "user_id",
    "_ownerId": "organization_id",
    "_badgeId": "badge_definition_id",
    "creationDate": "2024-11-27T10:30:00.000Z",
    "expires": "2025-11-27T10:30:00.000Z",
    "disabled": false,
    "expiryReminderSent": false,
    "_lessonActiveIds": ["lesson_active_1", "lesson_active_2"],
    "ruleData": {
        // Badge rule specific data
    },
    "createdAt": "2024-11-27T10:30:00.000Z",
    "updatedAt": "2024-11-27T10:30:00.000Z"
}

See Payload Examples for complete, real-world payload examples.

Event Delivery Guarantees​

At-Least-Once Delivery​

Beedeez guarantees at-least-once delivery for webhook events:

  • Events will be delivered at least once to your endpoint
  • Due to retry logic, you may receive the same event multiple times
  • Design your webhook handler to be idempotent

Ordering​

  • Events are processed asynchronously through a queue system
  • Events are generally delivered in the order they occur
  • However, strict ordering is not guaranteed, especially during retries
  • Use date fields in the payload (like createdAt, updatedAt, creationDate) to determine actual event sequence

Reliability​

  • Failed deliveries are automatically retried (up to 100 attempts over 10 minutes)
  • Webhooks are processed with a concurrency of 5 parallel requests
  • The queue system ensures reliable delivery even during high load

Testing Events​

To test your webhook integration:

  1. Create Test Certificates: Set up test certificates in a development environment
  2. Award Test Certificates: Manually award certificates to test users
  3. Trigger Expiration: Create certificates with short validity periods
  4. Monitor Logs: Check your webhook endpoint logs for received events
  5. Verify Payload: Ensure the payload structure matches your expectations

Event Monitoring​

Monitor webhook event delivery through:

  • Webhook Statistics: Success/failure counts in the back office
  • Application Logs: Detailed logs of webhook processing
  • Your Endpoint Logs: Track received webhooks on your side
  • Monitoring Tools: Use APM tools to track webhook performance

Next Steps​