A powerful CLI tool that monitors your EventCatalog for changes and sends notifications (e.g. Slack, MS Teams, etc) when catalog changes are detected. Perfect for keeping teams informed about new dependencies in your event-driven architecture.
- 🔍 Smart Detection: Automatically detects when services add new event consumers
- 💬 Rich Slack Notifications: Beautiful, informative messages with EventCatalog links
- 🎯 Targeted Notifications: Only notifies relevant event owners
- 🧪 Dry Run Mode: Preview notifications before sending
- 🔧 Flexible Configuration: Support for multiple teams, channels, and custom headers
- ⚡ CI/CD Ready: Perfect for GitHub Actions and other CI systems
npm install -g @eventcatalog/notifier# Preview what notifications would be sent
eventcatalog-notifier --catalog ./my-eventcatalog --dry-run
# Send actual notifications
eventcatalog-notifier --catalog ./my-eventcatalog --config ./notifier.ymlCreate a notifier.yml file to configure your notifications:
# Version of the notifier config
version: 1.0.0
# The base URL for your EventCatalog
eventcatalog_url: https://eventcatalog.mycompany.com
owners:
# Team configuration
payments-team:
events:
- consumer-added # Get notified when services consume payment events
- consumer-removed # Get notified when services stop consuming payment events
- subscribed-schema-changed # Get notified when schemas change for consumed events
channels:
- type: slack
webhook: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
headers:
Authorization: 'Bearer xoxb-your-bot-token' # Optional custom headers
platform-team:
events:
- consumer-added
- consumer-removed
- subscribed-schema-changed
channels:
- type: slack
webhook: https://hooks.slack.com/services/T00000000/B00000001/YYYYYYYYYYYYYYYYYYYYYYYY
- type: slack # Multiple channels supported
webhook: https://hooks.slack.com/services/T00000000/B00000002/ZZZZZZZZZZZZZZZZZZZZZZZZ| Option | Description | Example |
|---|---|---|
--catalog <path> |
Path to your EventCatalog | --catalog ./eventcatalog |
--config <path> |
Path to notifier configuration | --config ./notifier.yml |
--commit-range <range> |
Git commit range to analyze | --commit-range HEAD~2..HEAD |
--dry-run |
Preview notifications without sending | --dry-run |
--verbose |
Enable detailed logging for debugging | --verbose |
The notifier currently supports the following event types:
| Event ID | Description | When It Triggers |
|---|---|---|
consumer-added |
New Event Consumer | When a service starts consuming an event (adds to receives list) |
consumer-removed |
Event Consumer Removed | When a service stops consuming an event (removes from receives list) |
subscribed-schema-changed |
Subscribed Schema Changed | When a schema changes for an event that services are consuming |
- Triggers when: A service adds a new event to its
receivesarray - Notification includes: Event details, new consumer service, event owners, consumer team, impact description
- Use case: Keep event owners informed when new services start depending on their events
- Slack message: Rich formatted message with EventCatalog links and emoji indicators
- Triggers when: A service removes an event from its
receivesarray - Notification includes: Event details, service that removed consumption, event owners, service team, impact assessment
- Use case: Keep event owners informed when services stop depending on their events (potential breaking changes)
- Slack message: Warning-style message with EventCatalog links and removal indicators
- Triggers when: A producer modifies the schema of an event that other services are consuming
- Notification includes: Event details, schema diff (before/after), affected consumers, event owners, producer service information
- Use case: Alert teams when schemas change for events they depend on, helping prevent integration issues
- Slack message: Warning-style message with schema diff, EventCatalog links, and affected consumer information
- Schema support: Detects changes in
.json,.avro, and.protoschema files
More event types coming soon! We're working on support for ownership changes, deprecations, and more.
The EventCatalog Notifier uses GitOps principles to detect and notify about changes in your EventCatalog. Here's the step-by-step process:
- Uses Git commit history to compare versions of your EventCatalog
- Analyzes the difference between two commits (default:
HEAD~1..HEAD) - Only examines service files that have actually changed
- Leverages Git's built-in diff capabilities for accuracy
# The tool compares service definitions like this:
git diff HEAD~1..HEAD -- eventcatalog/services/Before (Previous commit):
---
id: EmailService
receives:
- id: UserRegistered
version: 1.0.0
---After (Current commit):
---
id: EmailService
receives:
- id: UserRegistered
version: 1.0.0
- id: PaymentProcessed # ← NEW!
version: 2.1.0
---- Detects Changes: Identifies new/removed items in
receivesarrays - Enriches Data: Fetches event details and owner information using EventCatalog SDK
- Filters Notifications: Only processes events that teams have configured to receive
- Avoids Spam: No notifications for events without owners or unmatched configurations
- Target Resolution: Maps event changes to interested teams via configuration
- Message Generation: Creates rich, contextual notifications with EventCatalog links
- Multi-Channel: Sends to all configured channels (Slack, Teams, etc.)
- Error Handling: Gracefully handles failures and provides clear feedback
- Version Control: All changes are tracked and auditable
- Branch Awareness: Can analyze any commit range or branch
- CI/CD Native: Perfect for automated workflows
- Historical Analysis: Can replay changes from any point in history
- Rollback Detection: Future support for detecting reverted changes
graph LR
A[Git Commit] --> B[File Changes]
B --> C[Service Analysis]
C --> D[Event Detection]
D --> E[Owner Lookup]
E --> F[Filter Config]
F --> G[Generate Message]
G --> H[Send Notification]
This approach ensures zero configuration drift - your notifications are always in sync with your actual EventCatalog changes, not dependent on external webhooks or manual triggers.
If you see errors like "unknown revision or path not in the working tree", this usually means:
- New repository: You need at least 2 commits for
HEAD~1..HEADto work - Insufficient history: Try a different commit range or check
git log --oneline - Wrong directory: Make sure you're in a Git repository
Use --verbose flag to see detailed debugging information:
eventcatalog-notifier --catalog ./eventcatalog --verbose --dry-runThe tool will provide user-friendly error messages and suggestions to help you resolve issues quickly.
Add this workflow to .github/workflows/eventcatalog-notifier.yml:
name: EventCatalog Change Notifications
on:
push:
branches: [main, master]
paths: ['eventcatalog/services/**']
pull_request:
paths: ['eventcatalog/services/**']
jobs:
notify-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Need full history for git diff
- uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install EventCatalog Notifier
run: npm install -g @eventcatalog/notifier
- name: Send Notifications
run: |
if [ "${{ github.event_name }}" == "pull_request" ]; then
eventcatalog-notifier --catalog ./eventcatalog --config ./notifier.yml --dry-run
else
eventcatalog-notifier --catalog ./eventcatalog --config ./notifier.yml
fi# Clone and install
git clone https://github.com/eventcatalog/notifier
cd notifier
npm install
# Run in development
npm run dev -- --catalog ./example-catalog --dry-run
# Run tests
npm test
# Build for production
npm run buildWe welcome contributions! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Ensure tests pass (
npm test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
EventCatalog Notifier is source-available software with a community-friendly licensing model designed to support sustainable development while keeping the code transparent and accessible.
- 📖 Transparent Source: View, study, and modify the code for evaluation purposes
- 🆓 Try Before You Buy: 14-day free trial to test in your environment
- 🔑 Production License Required: A license key is needed for production use
- 🚀 Future Open Source: Plans to become fully open source as the project matures
- 🔥 Start Your Free Trial: eventcatalog.cloud - No credit card required
- 💳 Purchase License: eventcatalog.dev/pricing - Flexible plans for teams of all sizes
This approach helps us:
- 🛡️ Maintain Quality: Dedicated resources for testing, documentation, and support
- ⚡ Rapid Development: Faster feature delivery and bug fixes
- 🤝 Community Focus: Fair pricing while keeping source code accessible
- 📈 Sustainable Growth: Long-term project viability without compromising on transparency
We believe in transparency without compromise - you can see exactly how the tool works, contribute improvements, and trust that your investment supports continued innovation.
- ✅ View and study the source code
- ✅ Modify for evaluation and testing
- ✅ Use with valid license key in production
- ✅ Contribute improvements via pull requests
- ❌ Remove license validation mechanisms
- ❌ Offer as a competing service
Questions about licensing? We're here to help! Reach out through our support channels below.
Made with ❤️ by the EventCatalog team