docs are cool

doc/SQUARE_WEBHOOK_SETUP.md

@@ -0,0 +1,191 @@
+# Square Webhook Setup - Quick Reference
+
+## Complete Setup Process
+
+### Step 1: Generate SSL Certificate
+```powershell
+# Generate PEM certificate
+python generate_cert.py
+# Creates: cert.pem, key.pem
+```
+
+### Step 2: Convert to P7B for Square
+```powershell
+# Convert PEM to P7B (PKCS#7) format
+python convert_to_p7b.py
+# Creates: cert.p7b
+```
+
+### Step 3: Start HTTPS Server
+```powershell
+# Start webhook server with HTTPS
+python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443 --hook-ssl-only
+
+# Server URLs:
+# Main:    http://localhost:7432/
+# Webhook: https://localhost:8443/hook (or https://yourdomain.com:8443/hook)
+```
+
+### Step 4: Configure Square Webhook
+
+1. **Upload P7B Certificate to Square:**
+   - Go to: https://developer.squareup.com/apps
+   - Select your application
+   - Navigate to: **Webhooks** → **Manage Notification Settings**
+   - Upload `cert.p7b` file
+   - This allows Square to verify webhook signatures
+
+2. **Add Webhook Subscription:**
+   - Still in Webhooks section
+   - Click **"Add Subscription"**
+   - Enter URL: `https://yourdomain.com:8443/hook`
+   - Select events to subscribe to (e.g., `inventory.count.updated`)
+   - Click **Save**
+
+### Step 5: Test the Webhook
+
+```powershell
+# Test from command line
+python src/test_webhook.py
+
+# Or manually with curl
+curl -X POST https://localhost:8443/hook \
+  -H "Content-Type: application/json" \
+  -d '{"type":"inventory.count.updated","merchant_id":"test"}'
+```
+
+## Production Deployment
+
+### Using Let's Encrypt (Recommended)
+
+```bash
+# 1. Get Let's Encrypt certificate (Linux/WSL)
+sudo certbot certonly --standalone -d yourdomain.com
+
+# 2. Convert to P7B for Square
+python convert_to_p7b.py \
+  --cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
+  --output square.p7b
+
+# 3. Upload square.p7b to Square Dashboard
+
+# 4. Run server
+python src/test_server.py \
+  --ssl-cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
+  --ssl-key /etc/letsencrypt/live/yourdomain.com/privkey.pem \
+  --host 0.0.0.0 \
+  --hook-port 443 \
+  --hook-ssl-only
+```
+
+### Using ngrok (Easy Testing)
+
+```powershell
+# Terminal 1: Start your server (HTTP is fine)
+python src/test_server.py --hook-port 8080
+
+# Terminal 2: Expose with ngrok (provides HTTPS automatically)
+ngrok http 8080
+
+# Use the ngrok HTTPS URL in Square:
+# Example: https://abc123.ngrok.io/hook
+
+# For P7B certificate with ngrok:
+# ngrok provides its own certificate, so you don't need to upload one to Square
+```
+
+## Webhook Event Types
+
+Common Square webhook events you can subscribe to:
+
+- `inventory.count.updated` - Inventory quantity changes
+- `catalog.version.updated` - Catalog item updates
+- `payment.created` - New payment received
+- `payment.updated` - Payment status changes
+- `order.created` - New order created
+- `order.updated` - Order status changes
+
+## Troubleshooting
+
+### Certificate Upload Fails
+- Ensure file is in P7B format (not PEM)
+- File must be valid PKCS#7 structure
+- Check file isn't corrupted: `openssl pkcs7 -print_certs -in cert.p7b`
+
+### Webhook Not Receiving Data
+1. Check server is running and accessible from internet
+2. Verify URL in Square Dashboard is correct
+3. Check firewall allows incoming traffic on webhook port
+4. Review server logs: `./logs/studspider.log`
+
+### SSL Certificate Errors
+- Self-signed certificates won't work with Square in production
+- Use Let's Encrypt or commercial CA for production
+- Use ngrok for quick testing (provides valid HTTPS)
+
+### Testing Locally
+```powershell
+# Square can't reach localhost - use one of these:
+# 1. ngrok (easiest)
+ngrok http 8443
+
+# 2. Cloudflare Tunnel
+cloudflared tunnel --url http://localhost:8443
+
+# 3. Deploy to cloud (AWS, Azure, DigitalOcean, etc.)
+```
+
+## Verifying Webhook Signatures
+
+Square signs webhook requests. Your server should verify signatures:
+
+```python
+# TODO: Add to hook_handler in test_server.py
+import hmac
+import hashlib
+
+def verify_square_signature(payload: bytes, signature: str, webhook_signature_key: str) -> bool:
+    """Verify Square webhook signature"""
+    computed_signature = hmac.new(
+        webhook_signature_key.encode('utf-8'),
+        payload,
+        hashlib.sha256
+    ).digest()
+    
+    expected_signature = base64.b64decode(signature)
+    return hmac.compare_digest(computed_signature, expected_signature)
+```
+
+Get your webhook signature key from Square Dashboard → Webhooks → Signature Key.
+
+## Environment Variables
+
+Add to your `.env` file:
+
+```env
+# Square Webhook Configuration
+SQUARE_WEBHOOK_SIGNATURE_KEY=your_signature_key_from_square_dashboard
+
+# SSL Certificate Paths (production)
+SSL_CERT_PATH=/path/to/fullchain.pem
+SSL_KEY_PATH=/path/to/privkey.pem
+```
+
+## Commands Quick Reference
+
+```powershell
+# Generate certificate
+python generate_cert.py
+
+# Convert to P7B
+python convert_to_p7b.py
+
+# Start HTTPS server
+python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443 --hook-ssl-only
+
+# Test webhook
+python src/test_webhook.py
+
+# Start with ngrok
+ngrok http 8443
+```