# MATTERMOST BTCPAY WEBHOOK SETUP
## Retrieve BTCPay Server Onion Addresses via Mattermost

**Domain:** thebankofdebbie.giize.com  
**Created:** September 10, 2025  
**Purpose:** Get BTCPay Server and Bitcoin onion addresses in Mattermost

---

## 🚀 **QUICK SETUP**

### Step 1: Install Node.js Dependencies
```bash
# On your BTCPay server
ssh -i vps_hardening_key -p 2255 ubuntu@thebankofdebbie.giize.com
cd ~
mkdir mattermost-webhook
cd mattermost-webhook

# Copy webhook script
scp -i ../vps_hardening_key -P 2255 mattermost_btcpay_webhook.js ubuntu@thebankofdebbie.giize.com:~/mattermost-webhook/

# Install Node.js if not present
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install dependencies
npm init -y
npm install express
```

### Step 2: Configure Environment Variables
```bash
# Create environment file
cat > .env << 'EOF'
MATTERMOST_TOKEN=your-mattermost-outgoing-webhook-token
WEBHOOK_SECRET=your-webhook-secret-key
PORT=3001
EOF

# Set permissions
chmod 600 .env
```

### Step 3: Create Systemd Service
```bash
# Create systemd service file
sudo tee /etc/systemd/system/btcpay-webhook.service << 'EOF'
[Unit]
Description=BTCPay Mattermost Webhook Service
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/mattermost-webhook
ExecStart=/usr/bin/node mattermost_btcpay_webhook.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable btcpay-webhook
sudo systemctl start btcpay-webhook
sudo systemctl status btcpay-webhook
```

### Step 4: Configure UFW Firewall
```bash
# Allow webhook port (local only)
sudo ufw allow from 127.0.0.0/8 to any port 3001 comment "BTCPay-Webhook-Local"

# Check status
sudo ufw status numbered
```

---

## 📡 **MATTERMOST CONFIGURATION**

### Step 1: Create Outgoing Webhook in Mattermost
1. Go to **System Console** → **Integrations** → **Outgoing Webhooks**
2. Click **Add Outgoing Webhook**
3. Configure:
   - **Title:** BTCPay Server Info
   - **Channel:** Your desired channel (or leave blank for any channel)
   - **Trigger Words:** `!btcpay`
   - **Callback URLs:** `http://thebankofdebbie.giize.com:3001/webhook/btcpay`
   - **Token:** Copy the generated token for your `.env` file

### Step 2: Update Environment Variables
```bash
# Update with actual Mattermost token
nano ~/mattermost-webhook/.env

# Set the token you got from Mattermost
MATTERMOST_TOKEN=abc123def456ghi789
WEBHOOK_SECRET=your-secret-key-here
PORT=3001

# Restart service
sudo systemctl restart btcpay-webhook
```

---

## 🧅 **USAGE IN MATTERMOST**

### Available Commands:
- `!btcpay` - Get onion addresses
- `!btcpay onion` - Get onion addresses  
- `!btcpay status` - Get system status
- `!btcpay help` - Show help

### Example Output:
```
## 🧅 BTCPay Server Information

Domain: thebankofdebbie.giize.com

🌐 Clearnet Access:
• https://thebankofdebbie.giize.com

🧅 Tor Hidden Services:
• BTCPay: abc123def456ghi789klmnopqrstuvwxyz123456789.onion
• Bitcoin P2P: xyz987uvw654tsr321opnmlkjihgfedcba987654321.onion

🔐 Access Methods:
• Tor Browser: http://abc123...onion
• SSH Tunnel: ssh -L 8080:localhost:80 ubuntu@thebankofdebbie.giize.com

⚡ Integration:
• API Endpoint: https://thebankofdebbie.giize.com/api
• Webhook URL: https://thebankofdebbie.giize.com/webhook
• Onion API: http://abc123...onion/api

🔒 Security Status: ✅ Tor-enabled, Pruned Bitcoin, Hardened VPS
📅 Updated: 2025-09-10 14:30:15
👤 Requested by: admin
```

---

## 🔧 **ADVANCED CONFIGURATION**

### Reverse Proxy Setup (Optional)
If you want to expose the webhook via HTTPS:

```bash
# Add to nginx config for thebankofdebbie.giize.com
sudo tee -a /etc/nginx/sites-available/default << 'EOF'

location /webhook/btcpay {
    proxy_pass http://localhost:3001/webhook/btcpay;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;
}
EOF

# Test and reload nginx
sudo nginx -t
sudo systemctl reload nginx
```

### Security Enhancements
```bash
# Limit webhook to specific users
# Edit mattermost_btcpay_webhook.js
nano ~/mattermost-webhook/mattermost_btcpay_webhook.js

# Update allowed_users array:
allowed_users: ['admin', 'sysadmin', 'your-username']

# Restart service
sudo systemctl restart btcpay-webhook
```

### Monitoring & Logs
```bash
# Check webhook logs
sudo journalctl -u btcpay-webhook -f

# Test webhook directly
curl -X GET http://localhost:3001/webhook/btcpay/test

# Check health
curl http://localhost:3001/health
```

---

## 🚨 **SECURITY CONSIDERATIONS**

### ✅ **Security Features:**
- Webhook runs on localhost (not exposed externally)
- Token-based authentication
- User authorization (configurable allow-list)
- No sensitive data logged
- Service runs as non-root ubuntu user

### ⚠️ **Important Notes:**
- **Onion addresses are sensitive** - only share with trusted users
- **Limit Mattermost webhook access** to authorized team members
- **Monitor webhook logs** for suspicious activity
- **Rotate tokens periodically** for security

### 🔒 **Recommended Setup:**
1. Use private Mattermost channel for BTCPay commands
2. Limit webhook users to admins only
3. Enable webhook only when needed
4. Monitor access logs regularly

---

## 🔄 **MAINTENANCE**

### Regular Tasks:
```bash
# Check service status
sudo systemctl status btcpay-webhook

# Update webhook script
cd ~/mattermost-webhook
# Copy new version, then:
sudo systemctl restart btcpay-webhook

# View logs
sudo journalctl -u btcpay-webhook --since "1 hour ago"

# Test onion address retrieval
curl -s http://localhost:3001/webhook/btcpay/test | jq .
```

### Troubleshooting:
```bash
# Service not starting
sudo systemctl status btcpay-webhook -l
sudo journalctl -u btcpay-webhook -f

# Can't read onion addresses
ls -la /var/lib/docker/volumes/generated_tor_servicesdir/_data/
sudo cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostname

# Webhook not responding in Mattermost
curl -X POST http://localhost:3001/webhook/btcpay \
  -H "Content-Type: application/json" \
  -d '{"token":"your-token","user_name":"admin","text":"!btcpay"}'
```

---

## 📞 **SUPPORT**

### Common Issues:
1. **"Service unavailable"** - Check if BTCPay containers are running
2. **"Onion addresses not found"** - Wait 5 minutes after BTCPay startup
3. **"Access denied"** - Add your Mattermost username to allowed_users
4. **"Token invalid"** - Update MATTERMOST_TOKEN in .env file

### Files to Backup:
- `~/mattermost-webhook/mattermost_btcpay_webhook.js`
- `~/mattermost-webhook/.env` (contains tokens)
- `/etc/systemd/system/btcpay-webhook.service`

---

**🎯 Ready to use! Type `!btcpay` in your Mattermost channel to get BTCPay Server information.**