0726d0337b
- Add SubagentStop HTTP hook to .claude/settings.json pointing at n8n - Add importable n8n workflow (claude-agent-done.json): webhook trigger → extract agent name → POST to Discord - Add setup guide (claude-agent-notifications.md) with payload reference, test curl command, and future extension notes - Update n8n CONTEXT.md and workflows/README.md with new workflow entry Discord webhook URL is stored as n8n variable DISCORD_CLAUDE_ALERTS_WEBHOOK to keep it out of local config files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
355 lines
12 KiB
Markdown
355 lines
12 KiB
Markdown
# n8n Workflows Documentation
|
|
|
|
Collection of production n8n workflows and integration guides.
|
|
|
|
## Available Workflows
|
|
|
|
### Claude Agent Done → Discord
|
|
|
|
**Status:** Production Ready
|
|
**Purpose:** Discord notification when a Claude Code subagent finishes
|
|
|
|
**Quick Links:**
|
|
- 📖 **[claude-agent-notifications.md](claude-agent-notifications.md)** - Setup guide and payload reference
|
|
- 📦 **[claude-agent-done.json](claude-agent-done.json)** - Importable n8n workflow
|
|
|
|
**Features:**
|
|
- Triggered by Claude Code's `SubagentStop` HTTP hook
|
|
- Extracts agent name from the event payload
|
|
- Posts a completion message to Discord
|
|
- Discord webhook URL kept in n8n variables (not local config)
|
|
|
|
**Webhook URL:**
|
|
- Test: `http://10.10.0.210:5678/webhook-test/claude-agent-done`
|
|
- Production: `http://10.10.0.210:5678/webhook/claude-agent-done`
|
|
|
|
---
|
|
|
|
### Ko-fi → Paper Dynasty Integration
|
|
|
|
**Status:** Production Ready
|
|
**Purpose:** Automated pack distribution for Ko-fi shop purchases
|
|
|
|
**Quick Links:**
|
|
- 🚀 **[QUICK-START.md](QUICK-START.md)** - Get running in 30 minutes
|
|
- 📖 **[kofi-paper-dynasty.md](kofi-paper-dynasty.md)** - Complete setup guide and node configuration
|
|
- 🧪 **[kofi-testing-guide.md](kofi-testing-guide.md)** - Testing procedures and sample payloads
|
|
- 🗺️ **[kofi-product-mapping-template.json](kofi-product-mapping-template.json)** - Product configuration template
|
|
- 📝 **[kofi-implementation-notes.md](kofi-implementation-notes.md)** - Real implementation, gotchas, and lessons learned
|
|
|
|
**Features:**
|
|
- Receives Ko-fi webhooks securely
|
|
- Multi-method user identification (discord_userid or team abbrev)
|
|
- Flexible product mapping system
|
|
- Paper Dynasty API integration
|
|
- Discord notifications for all outcomes
|
|
- Comprehensive error handling
|
|
- Manual review workflow for edge cases
|
|
|
|
**Webhook URLs:**
|
|
- Test: `https://n8n.manticorum.com/webhook-test/kofi-paperdy`
|
|
- Production: `https://n8n.manticorum.com/webhook/kofi-paperdy`
|
|
|
|
---
|
|
|
|
## Documentation Structure
|
|
|
|
### Quick Start Guide
|
|
**File:** `QUICK-START.md`
|
|
**Audience:** First-time setup
|
|
**Time:** 30 minutes
|
|
**Contents:**
|
|
- Prerequisites checklist
|
|
- Step-by-step setup (8 steps)
|
|
- Post-setup tasks
|
|
- Quick troubleshooting
|
|
|
|
### Complete Setup Guide
|
|
**File:** `kofi-paper-dynasty.md`
|
|
**Audience:** Detailed implementation
|
|
**Contents:**
|
|
- Architecture overview
|
|
- Prerequisites and configuration
|
|
- Node-by-node workflow setup
|
|
- Discord notification templates
|
|
- Troubleshooting guide
|
|
- Monitoring and maintenance
|
|
|
|
### Testing Guide
|
|
**File:** `kofi-testing-guide.md`
|
|
**Audience:** QA and validation
|
|
**Contents:**
|
|
- 5-phase testing strategy
|
|
- 8 test scenarios with cURL commands
|
|
- Validation scripts
|
|
- Testing checklist
|
|
- Production monitoring
|
|
|
|
### Product Mapping Template
|
|
**File:** `kofi-product-mapping-template.json`
|
|
**Audience:** Configuration reference
|
|
**Contents:**
|
|
- JSON structure for n8n custom variable
|
|
- Example product configurations
|
|
- Pack type reference
|
|
- Naming conventions
|
|
- Usage examples
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### New to Ko-fi Integration?
|
|
|
|
1. **Start here:** [QUICK-START.md](QUICK-START.md)
|
|
2. **Need details?** [kofi-paper-dynasty.md](kofi-paper-dynasty.md)
|
|
3. **Ready to test?** [kofi-testing-guide.md](kofi-testing-guide.md)
|
|
|
|
### Adding New Products?
|
|
|
|
1. Open [kofi-product-mapping-template.json](kofi-product-mapping-template.json)
|
|
2. Copy an existing product configuration
|
|
3. Update Ko-fi product code and pack details
|
|
4. Add to n8n custom variable `KOFI_PRODUCT_MAP`
|
|
5. Create matching product in Ko-fi shop
|
|
6. Test with cURL before going live
|
|
|
|
### Troubleshooting?
|
|
|
|
**Quick Fixes:**
|
|
- Webhook 404: Check workflow is Active in n8n
|
|
- Token error: Verify Ko-fi token in n8n credential
|
|
- Team not found: Check discord_userid or message field
|
|
- Packs not granted: Review API response in execution log
|
|
|
|
**Detailed Help:**
|
|
- Full troubleshooting: `kofi-paper-dynasty.md` → Troubleshooting section
|
|
- Test scenarios: `kofi-testing-guide.md` → Common Issues
|
|
- Quick reference: `QUICK-START.md` → Troubleshooting
|
|
|
|
---
|
|
|
|
## Workflow Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Ko-fi Shop Order │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
│ POST webhook
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ n8n Webhook: /webhook/kofi-paperdy │
|
|
│ - Parse form data │
|
|
│ - Validate Ko-fi token │
|
|
│ - Filter shop orders only │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Identify Paper Dynasty Team │
|
|
│ • discord_userid → gmid lookup │
|
|
│ • OR message field → team abbrev │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
│
|
|
┌─────────┴─────────┐
|
|
│ Team Found? │
|
|
└─────────┬─────────┘
|
|
Yes ↓ ↓ No
|
|
│ └──→ Manual Review Discord Notification
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Map Ko-fi Products → Paper Dynasty Packs │
|
|
│ • Load KOFI_PRODUCT_MAP variable │
|
|
│ • Map shop_items to pack requests │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Call Paper Dynasty API: POST /packs │
|
|
│ • Grant packs to team │
|
|
│ • Auto-retry on failure (3x) │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
│
|
|
┌─────────┴─────────┐
|
|
│ API Success? │
|
|
└─────────┬─────────┘
|
|
Yes ↓ ↓ No
|
|
│ └──→ Error Discord Notification
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Success Discord Notification │
|
|
│ • Customer name and team │
|
|
│ • Packs granted │
|
|
│ • Transaction ID │
|
|
└──────────────────┬──────────────────────────────────┘
|
|
↓
|
|
Return 200 OK to Ko-fi
|
|
```
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
|
|
- n8n instance running at `https://n8n.manticorum.com`
|
|
- PostgreSQL database for execution history
|
|
- HTTPS access via Nginx Proxy Manager
|
|
- WebSocket support enabled
|
|
|
|
### Required Credentials
|
|
|
|
1. **Ko-fi Verification Token**
|
|
- Source: Ko-fi dashboard → Settings → API → Webhooks
|
|
- Format: UUID (e.g., `8c2a3835-4544-4f27-a53a-adfd1fcc5664`)
|
|
- Security: Validates webhook authenticity
|
|
|
|
2. **Paper Dynasty API Key**
|
|
- Source: Paper Dynasty admin
|
|
- Format: Bearer token
|
|
- Permissions: Read teams, write packs
|
|
|
|
3. **Discord Webhook URL**
|
|
- Source: Discord channel → Integrations → Webhooks
|
|
- Format: `https://discord.com/api/webhooks/...`
|
|
- Purpose: Success/error/manual review notifications
|
|
|
|
### Required Custom Variables
|
|
|
|
1. **KOFI_PRODUCT_MAP**
|
|
- Type: JSON object
|
|
- Location: n8n → Settings → Variables
|
|
- Purpose: Map Ko-fi product codes to PD packs
|
|
- Template: `kofi-product-mapping-template.json`
|
|
|
|
---
|
|
|
|
## Monitoring & Maintenance
|
|
|
|
### Daily Monitoring
|
|
|
|
- ✅ Check Discord for notifications
|
|
- ✅ Review failed executions in n8n
|
|
- ✅ Verify packs granted correctly
|
|
|
|
### Weekly Tasks
|
|
|
|
- 📊 Review n8n execution statistics
|
|
- 🔍 Check for unknown product codes
|
|
- 📝 Update product mapping if needed
|
|
- 🧪 Test new products before launch
|
|
|
|
### Monthly Tasks
|
|
|
|
- 💾 Backup n8n database
|
|
- 🔐 Rotate Ko-fi verification token
|
|
- 🔑 Rotate Paper Dynasty API key
|
|
- 📖 Update documentation with lessons learned
|
|
|
|
### Quarterly Tasks
|
|
|
|
- 🔧 Optimize workflow performance
|
|
- 📈 Review transaction analytics
|
|
- 🛡️ Security audit (credentials, access logs)
|
|
- 🧪 Test disaster recovery procedure
|
|
|
|
---
|
|
|
|
## Support & Resources
|
|
|
|
### Internal Documentation
|
|
|
|
- **n8n Infrastructure:** `/productivity/n8n/CONTEXT.md`
|
|
- **n8n Troubleshooting:** `/productivity/n8n/troubleshooting.md`
|
|
- **Paper Dynasty API:** `/home/cal/.claude/skills/paper-dynasty/SKILL.md`
|
|
|
|
### External Resources
|
|
|
|
- **n8n Documentation:** https://docs.n8n.io/
|
|
- **Ko-fi Webhook API:** https://help.ko-fi.com/hc/en-us/articles/360004162298
|
|
- **n8n Community:** https://community.n8n.io/
|
|
- **n8n Webhook Templates:** https://n8n.io/workflows/?categories=Webhooks
|
|
|
|
### Getting Help
|
|
|
|
1. **Check execution logs:** n8n → Executions → Filter by workflow
|
|
2. **Review Discord notifications:** Look for error details and transaction IDs
|
|
3. **Test with cURL:** Isolate webhook vs API vs n8n issues
|
|
4. **Consult troubleshooting guides:** Each doc has troubleshooting section
|
|
5. **Manual intervention:** Use Discord notifications to process failed orders
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
### Webhook Security
|
|
|
|
✅ **Token Validation:** All webhooks validated against Ko-fi verification token
|
|
✅ **HTTPS Only:** All communication encrypted via NPM SSL
|
|
✅ **Rate Limiting:** Configure in NPM for webhook endpoints
|
|
✅ **Path Obfuscation:** Use non-obvious webhook paths
|
|
|
|
### Credential Management
|
|
|
|
✅ **Encrypted Storage:** n8n encrypts credentials with N8N_ENCRYPTION_KEY
|
|
✅ **No Hardcoding:** Never hardcode secrets in workflows
|
|
✅ **Regular Rotation:** Quarterly rotation schedule for tokens
|
|
✅ **Backup Security:** Store encryption key in password manager
|
|
|
|
### Data Privacy
|
|
|
|
✅ **PII Handling:** Minimize customer data in logs and notifications
|
|
✅ **Retention Policy:** Auto-delete old executions (30 days)
|
|
✅ **Sanitized Logging:** Remove sensitive fields from error logs
|
|
✅ **GDPR Compliance:** Data deletion mechanism available
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
### Adding New Workflows
|
|
|
|
1. Create workflow documentation (follow `kofi-paper-dynasty.md` structure)
|
|
2. Add testing guide with sample payloads
|
|
3. Update this README with workflow description
|
|
4. Create quick-start guide if complex
|
|
5. Update `/productivity/n8n/CONTEXT.md` with workflow details
|
|
|
|
### Documentation Standards
|
|
|
|
- **Markdown format** for all docs
|
|
- **Code blocks** with language syntax highlighting
|
|
- **cURL examples** for all webhook tests
|
|
- **Screenshots** where helpful (workflow diagrams)
|
|
- **Version history** in Change Log section
|
|
|
|
### Testing Requirements
|
|
|
|
- ✅ Test with simulated webhooks (cURL)
|
|
- ✅ Test with real data in `/webhook-test/` path
|
|
- ✅ Validate all error paths
|
|
- ✅ Verify Discord notifications
|
|
- ✅ Test edge cases and invalid data
|
|
|
|
---
|
|
|
|
## Change Log
|
|
|
|
### 2025-11-13 - Ko-fi Integration
|
|
- Added Ko-fi → Paper Dynasty workflow
|
|
- Created comprehensive documentation suite
|
|
- Implemented multi-method user identification
|
|
- Added Discord notification system
|
|
- Created testing guide with 8 scenarios
|
|
- Documented product mapping system
|
|
|
|
---
|
|
|
|
## License & Attribution
|
|
|
|
**n8n:** Fair-code licensed (n8n GmbH)
|
|
**Workflows:** Created by Cal Corum for Paper Dynasty
|
|
**Documentation:** MIT License
|
|
|
|
---
|
|
|
|
**Questions?** Consult the [QUICK-START.md](QUICK-START.md) guide or review workflow-specific documentation.
|