claude-home/productivity/n8n/workflows

n8n Workflows Documentation

Collection of production n8n workflows and integration guides.

Available Workflows

Ko-fi → Paper Dynasty Integration

Status: Production Ready Purpose: Automated pack distribution for Ko-fi shop purchases

Quick Links:

• 🚀 QUICK-START.md - Get running in 30 minutes
• 📖 kofi-paper-dynasty.md - Complete setup guide and node configuration
• 🧪 kofi-testing-guide.md - Testing procedures and sample payloads
• 🗺️ kofi-product-mapping-template.json - Product configuration template
• 📝 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
2. Need details? kofi-paper-dynasty.md
3. Ready to test? kofi-testing-guide.md

Adding New Products?

1. Open 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 guide or review workflow-specific documentation.