Cloudflare and webhooks
Some services tell you about events by calling a URL: GitHub when CI finishes, Meta when someone comments. Mandala receives them on a separate local port that serves nothing but these webhooks, and a Cloudflare tunnel exposes only those paths to the internet. The app itself is never reachable through the tunnel.
The webhook listener
Mandala listens on 127.0.0.1:8788 (MANDALA_WEBHOOK_LISTEN) for:
| Path | From | Checked by |
|---|---|---|
/hooks/github | GitHub deliveries | The webhook secret's signature |
/hooks/meta | Meta's verification and comment events | The verify token and the app secret's signature |
/hooks/meta-media | Meta fetching an approved post's media | A one-day link per file, only while its post publishes |
Everything else answers 404. Each delivery is admitted once.
Connect Cloudflare
- Install
cloudflared(2025.4 or newer) at/usr/bin/cloudflared(or setALMA_CLOUDFLARED_PATH). Settings → Cloudflare shows Installed and whether the listener is up. - Create a Cloudflare API token with Zone Read, DNS Edit and Cloudflare Tunnel Edit, and paste it under Connection.
- Add an account with its Account ID (Cloudflare dashboard → account home), the Zone IDs your accomplice may read, the Webhook hostnames a tunnel may use (a dedicated one, such as
hooks.example.com), and whether it may Allow changes. Watch tunnels tells your accomplice when a tunnel's health changes. - Save.
Create the tunnel
Ask your accomplice: "set up the webhook tunnel on hooks.example.com for GitHub". It prepares a tunnel whose ingress is exactly the webhook paths to the listener (then 404), and a DNS record, and asks for your approval. Mandala then runs cloudflared itself, with the tunnel token stored sealed.
- Resume a stopped tunnel: your accomplice first checks at Cloudflare that the ingress and DNS are still exactly what you approved.
- Stop the connector (Settings): stops
cloudflared; the tunnel and DNS stay, so it can resume. - Adopt an existing tunnel: records a tunnel you created before as stopped, without changing anything at Cloudflare; then ask your accomplice to resume it.
- Removing the token stops the connector and forgets the tunnel token.
DNS and zones
With Allow changes, your accomplice can change DNS records and a few zone settings, each with your approval, re-checked against the record just before applying.