Relationships
#4407 serve: a webhook route can shadow serve's own API paths; require a fixed route prefix
Opened by skunk-ape · 11/4/2026· Shipped 11/9/2026
Closed: superseded by #4547. The fix for this issue (#3688) was reverted the same day (#3692). Operators may define a webhook on any path, and swamp-uat relies on routes under
/api/v1/hooks/. The/hooks/prefix now applies only to webhook route files (#4547).serve.yamland--webhookroutes keep the leading-slash check only. The Decision and Proposed change below are no longer current.
Problem
Webhook routes are matched before serve's HTTP API. The only validation on a route is that it starts with a slash (src/serve/serve_config.ts:812 and src/serve/webhook.ts:281), so a route can take over a POST path that serve itself answers.
Reproduced
On 3ff9a7030, against a scratch repo on loopback:
- With a route at /hooks/x, POST /api/v1/cancel returned 200 with cancellation_requested.
- With a route at /api/v1/cancel, the same request returned 401 Missing x-hub-signature-256 header, and serve logged the route as registered with no warning.
Only whoever controls the serve config can create a route today, so this is a misconfiguration risk rather than something an outside caller can trigger. It has to be closed before anyone other than the operator can create routes (see #3434).
Decision
Webhook routes always live under a fixed prefix, so they can never shadow a server route, now or as serve adds paths. The prefix is not optional and not disableable.
Proposed change
- Define one constant prefix, /hooks/. It fits existing usage: 102 of the 109 routes in the manual, the source tree, integration tests and swamp-uat already use it. The one non-prefixed example in the manual is a --webhook /deploy example.
- Enforce it in both places routes enter: serve.yaml webhooks (including reload and check-config) and --webhook flags.
- Refuse a route that is the bare prefix, or that has empty, dot or dot-dot segments.
- Add an architecture fitness test so no serve HTTP route can be added under the prefix.
Open question
Deployed routes outside the prefix are senders' configured URLs and cannot be seen from here. Refusing them at boot on upgrade would stop a serve, so this needs a migration decision: refuse immediately, or warn for a release and then refuse. A reload that finds an invalid route keeps the previous route table, as it does today.
Out of scope
An additional admin-configured prefix layer, and stored routes; both belong to the design in #3434. Moving a route needs its sender's URL changed, so a manual update belongs in a sibling swamp-club issue.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.