Webhooks with Caddy

[clriis]

Webhooks have been cumbersome with nginx/apache/lighttpd due to HTTPS validation. Caddy simplifies this completely with automatic HTTPS.

Steps:

Install Caddy:

sudo apt install caddy

Ensure router/firewall allows ports 80/443 forwarded to your machine and the ports are not used by another application

Add this to /etc/caddy/Caddyfile:

# --- OneDrive Webhooks ---
    your.domain.tld {
        handle /webhooks/onedrive* {
            reverse_proxy 127.0.0.1:8888
        }
    }

Ensure 'your.domain.tld' reflects your own public URL

Validate and reload:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Configure ~/.config/onedrive/config per manual:

webhook_enabled = "true"
webhook_public_url = "your.domain.tld"

Reboot

[abraunegg]

@clriis

Webhooks have been cumbersome with nginx/apache/lighttpd due to HTTPS validation. Caddy simplifies this completely with automatic HTTPS.

An even simpler option is not to use webhooks - and use the native websocket support - the only requirement is your underlying curl version needs to support websockets :)

[clriis]

True. But Websocket is not reliable through NAT

[abraunegg]

I’m not sure I agree with that generalisation 🙂 — WebSockets are not inherently unreliable through NAT, and in fact the typical deployment model for WebSockets on the Internet assumes the client is behind NAT.

A few technical points that may help clarify how this works:

WebSockets are just TCP (usually over 443)

A WebSocket connection is established via an outbound TCP connection from the client to the server (HTTP Upgrade → persistent TCP stream).

From a NAT/firewall perspective this is indistinguishable from any other HTTPS connection:

• client opens outbound TCP → allowed by NAT
• NAT creates state table entry
• server replies on same 5-tuple → allowed back in
• connection stays open bidirectionally

So the server can push data to the client over that same socket even though the client is behind NAT — exactly the same as any long-lived HTTPS connection.

NAT only blocks inbound initiation, not established flows

The classic NAT limitation is that external hosts cannot initiate new connections to a private host.

But WebSockets don’t rely on inbound initiation — the client initiates the connection and keeps it open. Once established, the connection is full-duplex, so server→client messages traverse NAT with no special handling.

This is precisely why WebSockets are commonly used for “server push” to browsers and devices behind home routers.

The real issue: idle timeouts (not NAT incompatibility)

What can cause WebSocket drops through NAT is stateful device idle timeouts (home routers, firewalls, proxies, LB, etc).

If the TCP flow is idle long enough, the NAT mapping is removed and the next packet is dropped.
This is well-known for long-lived TCP/WebSocket connections.

The standard mitigation (and what most WebSocket stacks do) is:

• TCP keepalive (OS level), and/or
• WebSocket ping/pong frames (application level)

Those periodic frames keep the NAT state alive and prevent timeout.

Encrypted WebSockets (wss://) are NAT-friendly by design

WebSockets were explicitly designed to traverse proxies and intermediaries by tunnelling over HTTP(S) ports 80/443 and using HTTP CONNECT when needed.

In practice:

• wss:// over 443 looks exactly like TLS
• NAT/firewall devices treat it as normal HTTPS
• success rate is very high in real deployments

OneDrive client WebSocket implementation details

In the OneDrive Client for Linux, WebSocket connectivity is implemented as a standard outbound wss:// (TLS over TCP/443) client connection to the Microsoft Graph change notification endpoint, established using libcurl’s WebSocket support.

The connection is initiated from the client (typically behind NAT) exactly like a normal HTTPS request, upgraded to a persistent full-duplex WebSocket, and then maintained with periodic protocol-level keepalive (ping/pong) and automatic reconnect logic.

No inbound connectivity, port forwarding, or NAT traversal mechanisms are required because all change notifications are delivered over the already-established outbound TLS session.

If the connection is interrupted (e.g., network change, NAT idle timeout, proxy reset), the client transparently re-establishes the WebSocket and resumes notification processing, which is the same reliability model used by browsers and other Microsoft 365 sync clients operating behind consumer and enterprise NAT environments.

[clriis]

You are right!!! Websocket seems to now work brilliantly on my Laptop (TP X1 with Linux Mint 22.3)

Thank you!!!