ADR 0014: Refuse a webhook path without a leading slash¶
- Status: Accepted
- Date: 2026-11-11
Context¶
The url setting names the webhook path, the endpoint's only protection.
The composition root hands it to the inbound adapter, which registers it as
the app's one route
(ADR 0010).
A request path always starts with /. Starlette's own Route refuses a
path without one, but FastAPI's @app.post accepts it, so a url such as
strategy, hook/secret or a whole address like
https://host/strategy registered a route that no request could match:
- the bot printed its banners, logged in and served as usual;
- every alert got
404 Not Found, the same answer as a wrong address; - nothing in the bot's output said why.
An operator saw a healthy bot and no trades. The README warned about it in
the url row and in troubleshooting, but nothing stopped it.
Step 5a pinned it as a known defect
(test_a_path_without_a_leading_slash_starts_but_is_never_reachable).
Decision¶
--url is checked when the arguments are read. Its value must be
generate or start with /; anything else stops the bot like any other
invalid argument.
flowchart LR
ARG["--url value"] --> CHECK{"generate, or<br/>starts with /?"}
CHECK -- generate --> GEN["new random path,<br/>printed once (ADR 0012)"]
CHECK -- "/..." --> ROUTE["the app's one route"]
GEN --> ROUTE
CHECK -- "anything else" --> STOP["argparse error on stderr,<br/>exit 2, before the banners<br/>and the login"]
ROUTE --> SERVE[uvicorn serves it]
- Where: an argparse
type,webhook_url, in the composition root, next to the other start arguments. A bad value exits with status2before any output, the login and the server, exactly like an unknown environment or a port that is not a number. - The message leaves the value out:
argument --url: must start with / or be generate. The value is the operator's secret path, give or take a slash, and stderr goes to the same container log as everything else. argparse echoes a value rejected with aValueError, so the check raisesArgumentTypeError, which it prints as given. generatepasses untouched. It has no leading slash, and it is part of the frozen contract.- The empty value is refused too. It starts with no slash, and its route
matched nothing either. Through the image it never reaches the check:
the start command expands
urlunquoted, so an emptyurldrops out of the command line and argparse stops one step earlier, withargument --url: expected one argumentand the same status2.
What changes¶
This is a behaviour change.
url |
Before | After |
|---|---|---|
/strategy, /hook/secret, /hook/ |
served | served |
generate |
a new random path, served | the same |
strategy, hook/secret, https://host/strategy |
starts, every alert gets 404 |
exit 2, argument --url: must start with / or be generate |
| empty, through the image | argument --url: expected one argument, exit 2 |
the same |
| empty, passed to the script directly | starts, every alert gets 404 |
exit 2, argument --url: must start with / or be generate |
A bot started with such a url never handled a signal, so no working setup
breaks. What the operator sees changes: the container stops at once, with
the reason on stderr, instead of looking healthy. With the README's
--restart unless-stopped, Docker restarts it over and over, and
docker logs shows the same line each time until the setting is fixed.
The tests changed with it:
- The pin is replaced in
tests/characterization/test_startup.py:strategy,hook/secret,https://host/strategyand an empty value exit with status2, print nothing on stdout, never log in or serve, and end stderr with the exact message, with no part of the value anywhere in it. generateand a path chosen by hand keep their own startup tests.
All four cases failed before the fix: the bot started and served.
What this does not cover¶
-
A
urlwith braces is a pattern, not a path: FastAPI reads{name}as a path parameter, so the bot handles signals on paths the operator never set, and a pattern Starlette cannot compile, such as/{x:foo}, stops the bot with a traceback after the login. It starts with/, so this check lets it through. It is a known defect of its own in the migration roadmap.Update: step 6e (ADR 0015) refuses any
{or}inurlat startup, with the same exit status. - uvicorn's access log still writes the path of every request.Update: step 6f (ADR 0016) drops the request line, and with it the path, from the access line. - The image's
sh -ccommand expandsurlunquoted, like the credentials. A path with spaces or shell characters is split before the check sees it.
Consequences¶
- A
urlthat cannot be served is caught at startup, where the operator is looking, instead of as404s on the alert sender's side. - The README's
urlrow and the troubleshooting row no longer need to explain the silent case. - Images built before this step still start with such a
url; there, the README's earlier advice applies: start the path with/.
Alternatives considered¶
- Prepend the missing slash. Rejected: it guesses.
strategywould become/strategy, buthttps://host/strategywould become/https://host/strategy, a route that still matches nothing, and the bot would again look healthy. Refusing tells the operator what is wrong, and the fix is one character. - Check in the adapter, in
create_app. Rejected as the only check: by then the banners have been printed and the login made, so the bot would stop after logging in to the account, and with a traceback rather than the argument error every other bad setting gets. - Log a warning and serve anyway. Rejected: the route still matches nothing, so it is the same silent failure with one more line in the log.