studspider/doc/SQUARE_WEBHOOK_SETUP.md

Square Webhook Setup - Quick Reference

Complete Setup Process

Step 1: Generate SSL Certificate

# Generate PEM certificate
python generate_cert.py
# Creates: cert.pem, key.pem

Step 2: Convert to P7B for Square

# Convert PEM to P7B (PKCS#7) format
python convert_to_p7b.py
# Creates: cert.p7b

Step 3: Start HTTPS Server

# 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

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

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

# 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

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

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

# 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

# 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