Relationships
↔ sibling #4556#4551 Docs: serve skips webhook routes under its reserved path roots; recommend /hooks/
Opened by zack · 11/9/2026· Shipped 11/10/2026
What changed
swamp-club#4407 stops a webhook route from shadowing serve's own HTTP paths. Serve now skips a webhook route (from serve.yaml webhooks or --webhook) that:
- is the root path itself, or sits at or under a reserved root: health, ready, auth, api, internal, dashboard, data, bundle. Matching is on the first non-empty path segment, so /apiary is fine while /api and /api/github are skipped. A percent-encoded spelling of a root (such as /%61pi/x) is skipped too.
- has a dot or dot-dot segment (such routes could never match a delivery).
Only that webhook fails: serve starts and serves every other route, logs 'Webhook route skipped' (webhook_skipped in --json) with the reason, swamp serve reload applies the other routes and reports a warning, and swamp serve check-config lists it under Webhook warnings without failing.
Every other route stays valid, including existing routes outside /hooks/ such as /deploy. /hooks/ is reserved for webhooks: serve never adds its own route under it, so it is the recommended prefix for new routes.
Pages to update
- content/manual/reference/swamp-serve/webhooks.md: in the route row of the flag table, state the reserved roots, the dot-segment rule, that such a route is skipped, and that /hooks/ is recommended.
- content/manual/how-to/set-up-webhooks.md: recommend /hooks/ routes, and explain that a route under a reserved root is skipped (with a warning at startup, on reload and in check-config); moving it means changing the sender's configured URL.
- Any example using --webhook /deploy stays valid, but prefer a /hooks/ route in new examples.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.