studspider/doc/HTTPS_SETUP.md

# HTTPS Webhook Setup Guide

## Quick Start (Self-Signed Certificate for Testing)

### 1. Generate Certificate
```powershell
python generate_cert.py
```

This creates `cert.pem` and `key.pem` files.

### 1.5. Convert to P7B for Square (Required for Square Webhooks)
```powershell
python convert_to_p7b.py
```

This creates `cert.p7b` which Square needs for webhook signature verification.
Upload this P7B file to Square Developer Dashboard → Webhooks → Manage Notification Settings.

### 2. Run Server with HTTPS

#### Option A: HTTPS for webhook only (recommended for development)
```powershell
python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443 --hook-ssl-only
```
- Main server: `http://localhost:7432/` (HTTP)
- Webhook: `https://localhost:8443/hook` (HTTPS)

#### Option B: HTTPS for everything
```powershell
python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443
```
- Main server: `https://localhost:7432/` (HTTPS)
- Webhook: `https://localhost:8443/hook` (HTTPS)

#### Option C: Single port with HTTPS
```powershell
python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem
```
- Everything on: `https://localhost:7432/`

### 3. Test the Webhook

Update `src/test_webhook.py` to use HTTPS:
```python
url = "https://localhost:8443/hook"
```

Then run:
```powershell
python src/test_webhook.py
```

## Production Setup (with Real Certificate)

### Option 1: Let's Encrypt (Free, Recommended)

On Linux/WSL:
```bash
# Install certbot
sudo apt-get install certbot

# Generate certificate (replace yourdomain.com)
sudo certbot certonly --standalone -d yourdomain.com

# Certificates will be at:
# /etc/letsencrypt/live/yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/yourdomain.com/privkey.pem

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

### Option 2: Reverse Proxy (nginx/Caddy)

Run studspider on HTTP internally, use nginx/Caddy for HTTPS:

```nginx
# nginx config
server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /hook {
        proxy_pass http://localhost:7432/hook;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

Then run studspider normally:
```powershell
python src/test_server.py
```

## Troubleshooting

### "OpenSSL not found" Error
- **Windows**: Install from https://slproweb.com/products/Win32OpenSSL.html
- **Alternative**: Use Git Bash or WSL which include OpenSSL

### Self-Signed Certificate Warnings
- Normal for development
- Use `--insecure` flag with curl/tools for testing
- For production, get a proper certificate from Let's Encrypt

### Port 443 Already in Use
- Use a different port like 8443
- Or stop the service using port 443

### Certificate File Not Found
- Use absolute paths: `--ssl-cert C:\path\to\cert.pem`
- Or run from the directory containing the certificates

## Square Webhook Configuration

### Certificate Requirements
Square requires a **P7B (PKCS#7)** certificate file for webhook signature verification.

### Setup Steps:

1. **Generate your certificate** (if you haven't already):
   ```powershell
   python generate_cert.py
   ```

2. **Convert PEM to P7B format**:
   ```powershell
   # Basic conversion
   python convert_to_p7b.py
   
   # With intermediate certificates (production)
   python convert_to_p7b.py --cert fullchain.pem --chain intermediate.pem --output square.p7b
   ```

3. **Upload to Square Dashboard**:
   - Go to https://developer.squareup.com/
   - Navigate to your application
   - Click on "Webhooks"
   - Click "Manage Notification Settings"
   - Upload the `cert.p7b` file
   - Square will use this to verify webhook signatures

4. **Configure webhook URL in Square**:
   - Use your public HTTPS URL: `https://yourdomain.com:8443/hook`
   - Square requires valid SSL (not self-signed for production)

### Testing with Square Webhooks:

When setting up webhooks in Square Dashboard:
1. Use your HTTPS URL: `https://yourdomain.com:8443/hook`
2. Square requires valid SSL (not self-signed)
3. Consider using ngrok for local testing:
   ```powershell
   ngrok http 8443
   ```
   Then use the ngrok HTTPS URL in Square Dashboard