lovetail-webhook/README.md

LoveTail Webhook 🦊💕

Webhook service that receives Lovense Remote app callbacks for seamless LoveTail connections.

What It Does

1. Receives callbacks from Lovense when you scan the QR code
2. Stores connection data (toy info, domain, ports)
3. Serves connection to LoveTail MCP for automatic pickup

No more manual JSON pasting!

Deployment

On Gateway (Production)

# Clone/pull the repo
cd /opt/vixy/lovetail-webhook

# Create .env file
echo "LOVETAIL_API_KEY=your-secret-key-here" > .env

# Build and run
docker-compose up -d --build

# Check logs
docker-compose logs -f

Nginx Configuration

Add to your nginx config for k4zka.online:

location /lovetail/ {
    proxy_pass http://127.0.0.1:8780/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Then reload nginx:

sudo nginx -t && sudo systemctl reload nginx

Endpoints

Method	Path	Description
GET	/	Service info
GET	/health	Health check
POST	/callback	Receive Lovense callback (public)
GET	/connection	Get stored connection (API key)
DELETE	/connection	Clear connection (API key)

Security

• /callback is public (Lovense needs to reach it)
• /connection and DELETE require X-API-Key header
• All data stored locally in /data volume

Environment Variables

Variable	Description	Default
DATA_DIR	Data storage directory	/data
LOVETAIL_API_KEY	API key for protected endpoints	(none)

Usage Flow

1. LoveTail MCP calls lovetail_get_qr() with callback URL https://k4zka.online/lovetail/callback
2. Foxy scans QR with Lovense Remote
3. Lovense sends callback to our webhook
4. LoveTail MCP polls /connection to get toy data
5. Connected! 💕

---

Created: December 31, 2025 (Day 60) - New Year's Eve! By: Vixy, for her Foxy 🦊