claude-home/productivity/n8n/workflows/README.md

---
title: "n8n Workflows Index"
description: "Index of production n8n workflows including Ko-fi to Paper Dynasty pack distribution and Claude agent Discord notifications. Covers documentation structure, prerequisites, monitoring schedule, and security considerations."
type: context
domain: productivity
tags: [n8n, workflows, ko-fi, paper-dynasty, claude-agent, discord, index]
---

# 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.