ADR 0020: Refuse ?, # and % in the webhook path¶
- Status: Accepted
- Date: 2026-11-12
Context¶
The url setting names the webhook path, the endpoint's only protection.
Since step 6d it must start with /
(ADR 0014), and since step 6e it must
not contain { or }
(ADR 0015), so the route is
one path, not a pattern.
ADR 0015 left three characters open. In a URL, ?, # and % are syntax,
not part of the path:
?starts the query string. A sender that is givenhttps://host/a?brequests the path/a, with the queryb.#starts the fragment, which a client that parses the URL never sends.%starts an escape. uvicorn decodes the request path before Starlette matches it, so a request for/a%41bis matched as/aAb.
The route compares the operator's url with the decoded path as written,
so a route with any of the three is reached only percent-encoded. The
bot starts and looks up, and every alert sent to the URL the operator
typed gets 404 Not Found: the silent failure ADR 0014 removed for a
missing slash.
This was observed against the bot's own app on a real uvicorn server, with
http.client, which sends the path exactly as given:
url |
Path sent | Answer |
|---|---|---|
/a?b |
/a?b |
404: the server reads the path /a |
/a?b |
/a%3Fb |
200, handled |
/a#b |
/a%23b |
200, handled |
/a%41b |
/a%41b |
404: the server reads /aAb |
/a%41b |
/a%2541b |
200, handled |
/a%zzb |
/a%zzb |
200, handled: %zz is no escape, so it is not decoded |
http.client sends /a#b as it is, and the server reads #b as part of
the path. A sender that parses the URL, as a browser or Node's URL does,
drops it. What TradingView's client does was not observed.
Decision¶
--url is refused if it contains a ?, a # or a %, anywhere, by the
same argparse type that checks the leading slash and the braces.
flowchart LR
ARG["--url value"] --> GEN{"generate?"}
GEN -- yes --> NEW["new random path,<br/>printed once (ADR 0012)"]
GEN -- no --> SLASH{"starts with /?"}
SLASH -- no --> STOP1["exit 2: must start with /<br/>or be generate (ADR 0014)"]
SLASH -- yes --> BRACE{"has { or }?"}
BRACE -- yes --> STOP2["exit 2: must not<br/>contain { or } (ADR 0015)"]
BRACE -- no --> SYNTAX{"has ?, # or %?"}
SYNTAX -- yes --> STOP3["exit 2: must not<br/>contain ?, # or %"]
SYNTAX -- no --> ROUTE["the app's one route,<br/>reached as typed"]
NEW --> ROUTE
ROUTE --> SERVE[uvicorn serves it]
- Where:
webhook_urlin the composition root, after the brace check. A refused value exits with status2before any output, the login and the server, like every other bad argument. - The message leaves the value out:
argument --url: must not contain ?, # or %, raised asArgumentTypeErrorfor the reason ADR 0014 gives: argparse echoes a value rejected with aValueError, and stderr goes to the container's log. - One message per value. The leading slash is checked first, then the
braces, then these three, so
zq7?gets the slash message and/{zq7}?the brace message. - Every
%, not only one that starts a valid escape.%zzis not decoded, so/a%zzbreaches its route today. Refusing only%before two hex digits would mean an operator has to know the decoding rules to check their path by eye. generatecannot produce any of them. Its path comes fromsecrets.token_urlsafe, whose alphabet is letters, digits,-and_.
What changes¶
This is a behaviour change, and it can stop a bot that ran.
url |
Before | After |
|---|---|---|
/strategy, /hook/secret, generate |
served | the same |
/hook?x, /hook#x, /hook%41x |
served, reached only percent-encoded; an alert sent to the URL as typed gets 404 |
exit 2, argument --url: must not contain ?, # or % |
/hook%zzx, /hook/% |
served, reached as typed | exit 2, the same message |
- A path that worked only percent-encoded stops at startup. An operator whose alerts carried the encoded form has to choose a new path.
- A
%that is no escape, such as in/hook%zzx, worked and now stops too. This is the price of a rule that needs no knowledge of URL decoding. Such aurlis unlikely: the README's command andgeneratenever produce one.
In both cases the container stops at once with the reason on stderr. With
the README's --restart unless-stopped, Docker restarts it over and over,
and docker logs shows the same line each time until url is changed.
The tests changed with it, in tests/characterization/test_startup.py:
- A new pin,
test_a_path_with_a_query_fragment_or_escape_character_stops_and_is_not_echoed, covers/hook?zq7,/hook#zq7,/hook%41zq7,/hook%zq7and/hook/%. Each exits with status2, prints nothing on stdout, never logs in or serves, and ends stderr with the exact message, with no part of the value anywhere in it. All five failed before the fix: the bot logged in and served. - A new pin,
test_a_value_with_several_faults_gets_the_message_of_the_first_check, fixes the order of the three checks. - Each of these changes to the check fails at least one test: dropping any
one of the three characters, refusing
%only before two hex digits, raisingValueError, which echoes the value, and moving the check before the slash check or before the brace check.
What this does not cover¶
-
Other characters a sender may rewrite. A model of a sender that parses the URL, Node's
URLfollowed by the decoding uvicorn does, also changes:\, which it turns into/;.and..segments, which it resolves, as in/a/../bto/b;- tabs and line breaks, which it drops.
Whether a given sender does the same depends on its client:
curlandhttp.clientsend them as they are. They are not refused, since the rewrite was not observed for any sender of alerts; the README's command andgenerateproduce none of them. - Case./Hookis not/hook; the README says the path must match exactly.
Consequences¶
- Every
urlthe bot accepts is one path that a sender reaches by putting it in a URL as it is, with no encoding. - The README's
urlrow and troubleshooting table name the new message. - Images built before this step still start with such a
url; there, keep?,#and%out of it.
Alternatives considered¶
- Percent-encode the route. Register
quote(url)so that the decoded request path matches the typed one. Rejected: the operator would still have to send the encoded form, and?and#in the URL as typed would still cut the path. - Refuse everything outside a character allow-list, such as the characters RFC 3986 allows unescaped in a path. Rejected: it would also refuse spaces and letters outside ASCII, which a sender encodes and uvicorn decodes back, so they work today, for no gain against this defect.
- Also refuse
\,.and..segments and control characters. Rejected for this step: their rewrite depends on the client and was not observed for any sender of alerts (see "What this does not cover"). - Check in the adapter, in
create_app. Rejected for the reason ADR 0014 gives: by then the bot has logged in.