studspider/doc/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.

1.5. Convert to P7B for Square (Required for Square Webhooks)

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)

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

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

   python generate_cert.py
   

2. Convert PEM to P7B format:

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

   ngrok http 8443
   

   Then use the ngrok HTTPS URL in Square Dashboard