studspider/HTTPS_SETUP.md

HTTPS Webhook Setup Guide

Quick Start (Self-Signed Certificate for Testing)

1. Generate Certificate

python generate_cert.py

This creates cert.pem and key.pem files.

2. Run Server with HTTPS

Option A: HTTPS for webhook only (recommended for development)

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

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

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:

url = "https://localhost:8443/hook"

Then run:

python src/test_webhook.py

Production Setup (with Real Certificate)

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

On Linux/WSL:

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

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

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:

   ngrok http 8443
   

   Then use the ngrok HTTPS URL in Square Dashboard