The matrix notification bus: hookshot as a packaged app
Status: open design. The hookshot app is in the catalog (
apps/standalone/hookshot) and the bus is deployed. The transform render arms are still owed.
As written: PROPOSAL. Nothing here exists. There is no apps/*/hookshot, no
webhook socket, no producer plug, and no consumer of matrixAppservice
anywhere in the catalog. Every SHC surface below is specified, not reported.
⚠ CORRECTION 2026-08-10. The paragraph above was true on 2026-08-09 and is not any more: the provider half LANDED on
mainina78b60301(shipped v0.0.49):apps/communication/hookshot/exists,webhook.socket.yamlexists, andmatrixAppservicenow has two catalog consumers (huly-matrix-notifier, hookshot). Producer plugs remain unbuilt and no hookshot stack has ever been deployed. The current state map, and what the §12 measurements tell each still-owed §11 ruling, isdocs/proposals/2026-08-10-hookshot-phase0-readiness.md.
What is measured is the upstream: matrix-hookshot@main at version 7.4.4,
released 2026-08-05 (four days before this document), read file by file; the
matrix package’s own rendered registration, read out of its boot script; and
each of the four candidate producers, read against its own source or its own
vendor documentation. Where a claim came from a command or a line number, both
are printed.
★ Read §1 before §2. The brief this document was written against contains one factual error and one hidden assumption, and correcting them changes what should be built.
0. Measured, specified, owed
Section titled “0. Measured, specified, owed”| Class | Meaning | Marked |
|---|---|---|
| MEASURED | Read off pinned source or vendor docs, 2026-08-09 | plain statement, with its citation |
| SPECIFIED | This document decides it; no code exists | ”the app MUST…” |
| VERIFY | A concrete assumption with the one command that settles it | VERIFY |
| RULING OWED | An owner decision, not an agent’s to make | RULING OWED |
0.1 Measured, in one list
Section titled “0.1 Measured, in one list”- hookshot is an Apache-2.0 Matrix application service:
package.json:"name": "matrix-hookshot", "version": "7.4.4", "license": "Apache-2.0". Node 22 with a compiled Rust native module (Dockerfilestage 0 installsrustup,cmake,libssl-dev). Official imageghcr.io/matrix-org/matrix-hookshot. - It needs a registration with a
url, because Synapse must PUSH transactions to it. The matrix package’svars.appservice.urldefaults to"", which its boot script renders as an expliciturl: null, and that file’s own comment says what that means: “Null means send-only, right for a notification bot, wrong for a bridge, which must set vars.appservice.url to its own in-cluster endpoint or it will never receive a transaction.” - ★★ A static connection’s
hookIdIS itsstateKey:src/Connections/GenericHook.ts, theisStaticbranch, with upstream’s own comment: “Static connections define their own hookId via the stateKey. This is DANGEROUS if this was a user-defined connection, but we allow it because the administator set it.” That single fact is what makes a declarative, ledger-free, zero-chat-command bus possible at all (§4). - ★ The hookId is a bearer secret in a URL:
src/Webhooks.ts:19, and it is redacted from Prometheus labels only when it matches a v4 UUID:7.4.4’s sole changelog entry is “Do not log webhook URLs to prometheus metrics. Fixes GHSA-5c49-6fvm-2xvc.” A human-readable stateKey is therefore a secret that is not redacted. §5.3.const HOOK_ID_PATH_SEGMENT = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi; - ★ With no
generic.userIdPrefix, hookshot posts as the appservice bot itself:GenericHookConnection.getUserId():No ghost users, so the matrix package’s narrow defaultif (!this.config.userIdPrefix) { return this.intent.userId; }usersRegexneeds no widening. §3.4, and §3.4 also shows why the alternative is unavailable. - ★ With no
permissions:block, every user on the homeserver domain gets admin over the bridge.src/config/Config.ts:349-352logs it as a warning and continues. And the invite path is gated on it:onRoomInvite(src/Bridge.ts:1274) makes the bot leave unless the inviter passescheckPermissionAny(sender, BridgePermissionLevel.login). passFileis mandatory at runtime, not only for OAuth services:src/App/BridgeApp.ts:58callsUserTokenStore.fromKeyPath(config.passFile, …)unconditionally. It is a 4096-bit RSA private key (openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096).- The inbound path is
/webhook/<hookId>:src/Webhooks.ts:77-78mountsGenericWebhooksRouterat"/webhook"(with a deprecated second copy at/), andsrc/generic/Router.ts:125isrouter.all("/:hookId", …).POSTandPUTalways;GETonly whenenableHttpGetis true. - The default body contract is Slack/Mattermost-shaped:
transformHookData(GenericHook.ts:674), whose own comment cites Mattermost’s incoming-webhook parameters: a top-level stringtextbecomes the message, a top-level stringhtmlbecomes the formatted body, anything else is rendered as a fenced JSON block. matrixhas one consumer, not zero. §1.1.
0.2 What this document does not settle
Section titled “0.2 What this document does not settle”The provisioning API (hookshot has an src/api tree and a widget provisioner)
was not read. Everything below deliberately uses static connections in the
config file, because that path is measured and needs no secret-bearing HTTP
surface. If the provisioning API turns out to be the better effector, that is a
phase-2 revision, not a correction, and §10.2 names the command that decides.
1. Two corrections to the premise, first
Section titled “1. Two corrections to the premise, first”1.1 ★ matrix is not unconsumed; matrixAppservice is
Section titled “1.1 ★ matrix is not unconsumed; matrixAppservice is”The brief said the matrix package “already serves matrix + matrixAppservice
with zero consumers today.” Measured:
ls apps/*/*/matrix.plug.yaml # → apps/monitoring/uptime-kuma/matrix.plug.yamlls apps/*/*/matrixAppservice.plug.yaml # → no matchesmatrix has exactly one consumer and it is a working one.
apps/monitoring/uptime-kuma/matrix.plug.yaml is 200+ lines that drive Uptime
Kuma’s Socket.IO control channel to wire its built-in Matrix notification
provider to the socket’s room and bot token, including a measured
idempotency workaround (“the server has no upsert; addNotification with a
null id INSERTS every time”).
matrixAppservice is the socket with zero consumers, and that is the one
this document is about. The distinction is not pedantry: it means the
notification contract is proven and the masquerade contract is unproven,
so hookshot’s real value to the estate is not “notifications” (those already
work) but “the first thing that exercises the appservice registration end to
end.”
1.2 ★ Three of the four named producers can already reach Matrix without a bridge
Section titled “1.2 ★ Three of the four named producers can already reach Matrix without a bridge”The brief names gitlab, glitchtip, uptime-kuma and wazuh as producers that “should reach a matrix room.” Measured, one at a time:
| producer | native Matrix support? | evidence |
|---|---|---|
| uptime-kuma | yes, and SHC already wires it | apps/monitoring/uptime-kuma/matrix.plug.yaml, consuming the matrix socket’s accessToken + internalHomeserverUrl + roomId |
| gitlab | yes, natively, since 17.3 | GitLab’s Matrix project integration: Free/Premium/Ultimate, Self-Managed included, fields: hostname, token, room identifier, event triggers; configurable instance-wide under Admin → Settings → Integrations. shc pins gitlab/gitlab-ce:18.11.7-ce.0 (apps/devops/gitlab/vars.yaml:222), well past 17.3 |
| glitchtip | no | apps/alerts/constants.py on glitchtip-backend: RecipientType is exactly email, webhook (“General Slack-compatible webhook”), discord, googlechat, ntfy, teams, zulip, feishu. No Matrix. shc pins glitchtip/glitchtip:6.2.5 |
| wazuh | no | the integrator daemon’s built-in name values are slack, pagerduty, virustotal, shuffle, maltiverse, nothing else. Anything further is a custom-<name> script in /var/ossec/integrations/, root:wazuh, executable, invoked with <alert file> <api_key> <hook_url>. shc pins wazuh/wazuh-manager:4.14.7 |
★ So the honest scope of a Matrix bridge is two producers, not four. Routing GitLab and Uptime Kuma through hookshot would replace a native, richer, already-working path with a generic JSON-to-text renderer and a second daemon in the blast radius. That is a regression dressed as consolidation.
This does not kill the design; it sharpens it. hookshot earns its keep for producers that can emit a webhook but cannot speak Matrix, and there are two of those today. Everything below is written for that, and §6 is a per-producer verdict rather than a per-producer plug.
2. What hookshot actually is
Section titled “2. What hookshot actually is”An application service, in the Matrix sense: a process the homeserver
trusts by a shared token pair, which may act as a namespace of local users and
receives a push feed of events from the homeserver. It is not a bot with an
access token, and the difference is the whole reason it needs
matrixAppservice rather than matrix.
What it bridges, per its own README: Challenge Hound, Figma, Generic Webhooks, GitHub, GitLab, Jira, OpenProject, RSS/Atom. Only Generic Webhooks matters here; the rest are OAuth-coupled integrations with their own credential lifecycles, and §8 turns them all off explicitly.
Two design properties worth naming because they change the SHC cost:
- “No external database”: it uses Matrix state as storage. True for
connection state, which lives in room state events, and for generic hook
ids, which live in room account data. So there is no Postgres plug and no
postgres.plug.yamlto write. There is still a passkey file (§0.1.7) and an optional encryption store, both of which are per-deployment state that must survive a restart, sobackup.yamlis not empty. - Encryption needs Redis.
config.sample.yml: “(Optional) Cache options for large scale deployments. For encryption to work, this must be configured.” An unencrypted notification room needs none, and §8 does not ship one.
3. What hookshot needs from the homeserver and what the matrix package already gives
Section titled “3. What hookshot needs from the homeserver and what the matrix package already gives”3.1 The registration, key by key
Section titled “3.1 The registration, key by key”registration.sample.yml, mapped onto what matrixAppservice.socket.yaml
publishes:
| registration key | hookshot’s sample | socket key | fit |
|---|---|---|---|
id | matrix-hookshot | id (vars.appservice.id, default shc) | ✓ any unique string |
as_token | random | asToken@secret! | ✓ |
hs_token | random | hsToken@secret! | ✓, and the socket already says the consumer must verify incoming transactions against it |
sender_localpart | hookshot | senderLocalpart (default _shc_appservice) | ✓ Synapse always lets an appservice act as its own sender_localpart |
namespaces.users | @_github_.*, @_gitlab_.*, @_webhooks_.*, @feeds | usersRegex (default @_shc_[a-z0-9._=+/-]*:) | ⚠ §3.4 |
namespaces.aliases | #github_.+ | aliasesRegex (default "" ⇒ no namespace) | ✓ for generic webhooks; needed only by GitHub room-alias creation, which §8 disables |
url | http://localhost:9993 | not published; provider var only | ★ §3.2, the one real coupling |
rate_limited | false | vars.appservice.rateLimited | ✓ |
receive_ephemeral | true | not rendered at all | §3.5 |
3.2 ★ The one genuine coupling: appservice.url is authored on the provider
Section titled “3.2 ★ The one genuine coupling: appservice.url is authored on the provider”The matrix boot script renders the registration from provider vars only:
"url": os.environ.get("AS_URL", "") or None,with a comment stating the consequence exactly: “Null means send-only … wrong for a bridge, which must set vars.appservice.url to its own in-cluster endpoint or it will never receive a transaction.”
So bringing up hookshot requires two stacks touched in order:
shc update <matrix-stack> --var appservice.enabled=true \ --var appservice.url=http://<env>.hookshot.<hookshot-stack>:9993shc install hookshot -s <hookshot-stack> -i matrixAppservice=<matrix-stack> -i matrix=<matrix-stack>There is no way around this from the consumer side, and it should not be
disguised. The registration is provider policy by design: the socket’s own
header says the namespace is provider-authored “so binding a consumer can
never escalate what the token can impersonate”, and url rides the same
file. What the consumer can do is detect and report rather than
reconcile, which is the posture the frappe package already uses for the three
facts it may observe and must not repair:
- hookshot’s discovery job dials
<internalHomeserverUrl>/_matrix/client/v3/account/whoamiwithasToken(the same probecheck-appservice-registeredalready runs); that proves the registration is loaded but says nothing abouturl; - so a second, cheap check: the hookshot stack watches its own
:9993for a Synapse transaction (PUT /_matrix/app/v1/transactions/…). Nothing arriving within a bounded window meansurlis null or wrong, and the job says so with the exactshc updateline above and exits 0 rather than failing the install.
VERIFY: Synapse pushes a transaction only when there is an event to push. A
freshly-installed bridge in an empty room may legitimately see nothing, which
would make the check a false alarm. The reliable trigger is the invite of §5.4:
that membership event is an event in a room the bridge is interested in.
Settle with docker logs on the hookshot container after the invite.
3.3 The other provider preconditions
Section titled “3.3 The other provider preconditions”vars.appservice.enableddefaults false, and the boot script refuses to start Synapse when the registration cannot be written. So this is an explicit operator act, and the socket’s discovery job already turns “operator forgot” into a loud bind failure naming the fix.- The registration is one, shared.
matrixAppservice.socket.yamlsays so: “It is ONE registration, SHARED by every consumer that binds it … Two bridges that must not be able to impersonate each other need two registrations, which this app does not model yet.” With hookshot as the only consumer this costs nothing; a second bridge is what forces the extension. - Detaching revokes nothing. The socket’s unintegration job reports a
retained live token on the retained-cleanup channel. Killing the credential
is
--var appservice.enabled=false(all consumers) or rotating the two vault keys (all consumers, re-render survivors).
3.4 ★ The users namespace, and why the bus must post as the bot
Section titled “3.4 ★ The users namespace, and why the bus must post as the bot”The matrix package’s default is deliberately narrow:
usersRegex: "@_shc_[a-z0-9._=+/-]*:"Note what is not in that character class: _. So a hookshot
generic.userIdPrefix of _shc_webhooks_ mints @_shc_webhooks_gitlab:server,
and the regex (anchored at the start, requiring : immediately after the
class) cannot match it, because the class stops at the first underscore.
Synapse’s validate_appservice_can_control_user_id then refuses the
masquerade and the message never lands.
Three ways out, and only one of them is free:
| option | cost |
|---|---|
widen usersRegex on the matrix stack to admit underscores | an operator edit to a security boundary, on the provider, for cosmetics |
choose a userIdPrefix with no underscore inside the class, e.g. _shc_wh | fragile: the suffix is derived from the connection name, which may itself contain characters outside the class |
★ omit generic.userIdPrefix entirely | free, measured (§0.1.5): with no prefix, getUserId() returns this.intent.userId, the appservice’s own bot, which Synapse permits unconditionally |
The app MUST omit userIdPrefix. Every webhook then posts as
@_shc_appservice:<serverName> with the connection name carried in the message
body rather than in the sender. That is slightly less pretty in a client and it
is the difference between an integration that needs a provider-side security
change and one that does not.
3.5 receive_ephemeral, recorded so it is not rediscovered
Section titled “3.5 receive_ephemeral, recorded so it is not rediscovered”hookshot 7.4.3’s changelog: “Use the receive_ephemeral registration field
instead of legacy MSC ephemeral-event flags. Please ensure your registration
file is updated to match the new format.” The matrix package’s rendered
registration has no such key (the boot script’s dict is id, url,
as_token, hs_token, sender_localpart, rate_limited, namespaces, plus
io.element.msc4190 when enabled).
For a notification bus this is irrelevant: ephemeral events are read receipts,
typing and presence, none of which a webhook renderer needs. It is recorded
because it is a vars.appservice.receiveEphemeral the matrix package will owe
the day a bridge wants it, and because “the registration is missing a key
upstream now expects” is exactly the kind of thing that gets diagnosed twice.
4. Why a new app, and not machinery in the matrix package
Section titled “4. Why a new app, and not machinery in the matrix package”Three arguments, in increasing order of how much they should decide.
4.1 The matrix package’s discipline forbids it. That stack is Synapse +
MAS, every config file regenerated from vars on every boot, /data/appservices
rm -rf’d and rewritten at the top of the boot script, and a
tests/unit/catalog/matrix_appservice_directory_test.go that seeds a sibling
registration and runs the shipped boot text over it to prove the directory is
SHC-owned. Adding a Node-22-plus-Rust daemon, a second config file with a
different schema, an RSA passkey, an ingress host and an independent upgrade
cadence into that package would mean either weakening that discipline or
maintaining two of them.
4.2 The socket already exists and says this is its purpose.
matrixAppservice.socket.yaml was written for “bridges and bots that own an
identity space”, with a documented broker discipline (CONFINE / REVOKE /
VERIFY) mapped clause for clause onto mailcow’s credential brokering. It has
zero consumers. Machinery inside the matrix package would leave it at zero.
A bridge that consumes it is the only thing that can turn an argued design into
a proven one, and if consuming it turns out to be awkward, that is information
the socket needs and cannot get any other way.
4.3 The blast radii are different and the estate has already ruled on
mixing them. The matrix package is frozen-for-backup-trust infrastructure on
one estate; a webhook receiver is an internet-facing HTTP surface with a
payload parser and a bearer secret in a URL. matrix vs matrixAppservice
was split on precisely this reasoning (“handing them the alerts bot’s token
would be flatly wrong … Separate stems keep the blast radii separate, exactly
as mailcow splits smtp from imap”). Separate stacks are the same argument
one level up.
★ The honest counter-argument, stated because it is not weak: a new
packaged app is the most expensive unit of work in this catalog (§7), and
hookshot serves two producers (§1.2). If the answer to those two producers is
“write a Wazuh custom-matrix script and a tiny GlitchTip-shaped relay”, that
is a fraction of the cost and no new lifecycle. §9.1 takes that seriously
enough to make it phase 0.
5. The socket hookshot would serve to producers
Section titled “5. The socket hookshot would serve to producers”5.1 Applying the naming test honestly
Section titled “5.1 Applying the naming test honestly”plugs-and-sockets.md asks two questions. For a socket whose contract is
“POST a JSON body to this URL and it becomes a message”:
- Could a second, unrelated implementation serve it? Yes, and there are
many: Slack, Mattermost, Rocket.Chat, Discord’s
/slackcompatibility endpoint, ntfy, and (measured) GlitchTip’s ownGENERAL_WEBHOOKproducer emits the same shape. The de-facto contract is Slack’s incoming webhook, and hookshot implements it deliberately:transformHookData’s comment cites Mattermost’s parameter list. - Is
external-webhooknameable? Yes, an app that runs no service and publishes a URL the operator pasted, so a producer can post to a Slack workspace or a Discord channel instead. That is a real shim with a real use.
So the stem is webhook, and it is a capability socket under rule one, not
a singleton under rule two. hookshot as a stem would fail question 2 in the
same direction sso failed it, from the other side: it names the
implementation where a contract exists.
★ But the stem needs the same warning label matrix.socket.yaml carries.
That file has to say “The stem looks protocol-named, but the contract is a
notification bot: read the header rather than inferring the contract from the
stem.” webhook needs the mirror image: the stem looks like a transport, and
the contract is narrower than the transport: a JSON object whose top-level
text string is rendered as the message, and whose html string, if present,
is rendered as the formatted body. A consumer that POSTs some other shape
gets a fenced JSON dump in the room, which is legible and ugly, not an error.
The schema text MUST state that contract, because it is the only thing
standing between “a URL” and “a socket”.
5.2 What it publishes
Section titled “5.2 What it publishes”The hard constraint is mechanical: socket data: renders once per provider,
with no integration context (the existing sockets say so in as many words:
“This block renders ONCE per provider … so nothing here can vary per
consumer”). A per-producer webhook URL therefore cannot be a data key. It has
to be either mint-and-returned by an integration job (which only reaches a
consumer’s post_install/post_update hook render, never its compose or
its plug post_deployment job) or derived by the consumer from
provider-global values.
Derivation is the better half of that fork, and it is available because of §0.1.3:
stateKey = hookId = uuidshape( HMAC-SHA256( hookSecret, "<consumer-declared hook name>" ) )webhookUrl = <urlBase>/<stateKey>hookSecretis one provider-global secret (ref+vault://hookshot_hook_secret?autogen), so both ends compute the same value with no ledger, no enumeration endpoint and no read-back, the same stateless-derivation trick the frappe→Nextcloud calendar feed uses, for the same reason.- ★
uuidshapeis not decoration. §0.1.4: the metrics redaction regex matches a v4 UUID and nothing else. Formatting the digest into8-4-4-4-12with the version and variant nibbles set is what keeps the bearer secret out of Prometheus labels. A human-readable stateKey (gitlab,wazuh) is a secret printed in a metric label, which is the exact defect GHSA-5c49-6fvm-2xvc was filed for.
schema: plug: hook@string!: 'Name of the static connection this producer posts through. It is the HMAC input, so it is stable for the life of the edge; changing it changes the URL. Must match [a-z0-9-]+ and be UNIQUE per consumer; two consumers sharing a name share a bearer secret and a room connection.' socket: urlBase@url!: 'Base the per-producer URL is built on, INCLUDING the /webhook path segment. In-fabric by default; a producer outside the fabric needs the public one.' hookSecret@secret: 'Derivation secret. EMPTY on providers that do not derive (external-webhook publishes a complete `url` instead); guard every read with `| default('''')`.' url@url: 'A complete, ready-to-POST URL, when the provider has exactly one. Empty on a deriving provider. A consumer MUST prefer this when non-empty and derive only when it is not.' dialect@string!: 'Literal `slack`. The body shape the far end understands: a top-level string `text` becomes the message. Advertised so a consumer can refuse rather than post a shape that renders as a JSON dump.'Every provider-specific key is optional and | default('')-guarded, which is
the contract imap.socket.yaml states for its mailcow-only keys and the reason
external-webhook can serve the same stem while publishing neither
hookSecret nor urlBase.
5.3 The connection still has to exist on the provider, and that is honest work
Section titled “5.3 The connection still has to exist on the provider, and that is honest work”Deriving the URL does not create the hook. hookshot’s static connections live
in its own config.yml, read at startup:
connections: - connectionType: uk.half-shot.matrix-hookshot.generic.hook stateKey: <the derived uuid> roomId: "!alerts:example.org" state: name: glitchtipso the hookshot stack must already know the producer’s hook name at render time, and a socket integration job cannot add one without a restart. The posture that follows is detection, never reconciliation, which is exactly what the frappe package does for the three facts it can observe and must not repair:
-
the hookshot package takes
vars.hooks(a list of{name, room}) and renders both theconnections:block and, for each, the derived stateKey; -
the
webhooksocket’s integration job runscontext: serviceon the hookshot stack per consumer, so it can readintegration.plug.data.hook; it greps the rendered config for the derived stateKey and, when absent, prints the exact line that fixes it:webhook: this producer declared hook 'glitchtip', but no static connection withthat name exists on this bridge, so posts to its URL will answer 404.Add it, as operator, then re-bind:shc update <hookshot-stack> --var 'hooks=[{"name":"glitchtip","room":"<roomId>"}]'This integration will not write it for you: the connection list is providerconfiguration read at startup, and an edge-clocked write would let the lastconsumer to bind restart the bridge for every other one. -
and it exits 0, because a producer that cannot post yet is worth more than an install that refused.
★ The reasoning in that last clause is the same one that decided who writes
dav.calendarSubscriptionRefreshRate on the Nextcloud socket, and it lands the
same way: provider-global configuration is not a consumer’s to converge.
5.4 The bot must be in the room, and something has to invite it
Section titled “5.4 The bot must be in the room, and something has to invite it”ConnectionManager builds static connections for a room when the bridge
processes that room, and the bridge only processes rooms its bot is joined to.
An appservice cannot join a private room unilaterally.
Measured, hookshot does auto-accept invites: onRoomInvite
(src/Bridge.ts:1246) retries botUser.intent.joinRoom(roomId) five times,
but only after two gates:
if (!this.config.checkPermissionAny(event.sender, BridgePermissionLevel.login)) { return botUser.intent.underlyingClient.leaveRoom(roomId, "You do not have permission to invite this bot.");}So the inviter must be inside hookshot’s permissions: at login or above,
and the permissions block must exist, because its absence grants the whole
domain admin (§0.1.6), a posture that is both wrong and, on a homeserver with
open registration, dangerous.
★ Who issues the invite is the neat part, and it is why hookshot binds two
sockets. The matrix socket publishes accessToken for the alerts bot and
defaultRoomId for the room that matrix-init created as that bot, so
the bot holds PL 100 in it and can invite. A post_install hook job on the
hookshot stack, holding both socket renders, does:
curl -sf -X POST \ -H "Authorization: Bearer $${MATRIX_ACCESS_TOKEN}" \ -H 'Content-Type: application/json' \ --data "{\"user_id\":\"$${APPSERVICE_SENDER_USER_ID}\"}" \ "$${INTERNAL_HOMESERVER_URL}/_matrix/client/v3/rooms/$${ROOM_ID}/invite"then reads back the membership (GET /_matrix/client/v3/rooms/<id>/joined_members
must list the appservice sender) because the invite succeeding proves nothing
about the join, and this catalogue does not trust exit codes.
An already-joined member answers M_FORBIDDEN with “is already in the room”;
the converger reads that as converged, the third instance in this estate of
“idempotence expressed as an error” after dav:create-subscription and
occ user:add.
RULING OWED (§11.2): using the alerts bot’s token to invite stretches the
matrix socket’s stated contract (“post alerts into a room”). The alternative
is an operator invite, documented and manual. Recommendation: auto-invite with
the read-back, and a one-line note in the matrix socket header widening its
contract to “post into, and manage membership of, the room it created”.
6. Each producer, with a verdict
Section titled “6. Each producer, with a verdict”6.1 GlitchTip: the strongest case, and it needs one provider var
Section titled “6.1 GlitchTip: the strongest case, and it needs one provider var”Measured: RecipientType.GENERAL_WEBHOOK = "webhook", _("General Slack-compatible webhook"), and its payload is built by
apps/alerts/webhooks.py:
@dataclassclass WebhookPayload: text: str attachments: list[WebhookAttachment] | None★ A top-level string text is exactly what hookshot’s transformHookData
renders as the message. So GlitchTip → hookshot works with no
transformation function, no allowJsTransformationFunctions (which the
config sample flags as “unsafe in untrusted environments”), and the
attachments array rides along in the event’s
uk.half-shot.hookshot.webhook_data because includeHookBody defaults true.
That is the single cleanest producer/consumer fit in this document, and it is
measured on both sides.
★★ And there is an SSRF gate, exactly mirroring Nextcloud’s
allow_local_remote_servers. apps/alerts/webhooks.py:
async def _is_url_allowed(url: str) -> bool: """Runtime SSRF guard for outbound webhook URLs. …""" if await check_url_safe(url, allow_private=settings.GLITCHTIP_ALLOW_PRIVATE_IPS): return True logger.warning("webhook delivery blocked: URL resolves to a private/internal IP")checked twice (at alert-creation time by schema validation, and again at
send time to defeat DNS rebinding) and _post additionally refuses to follow
redirects. grep -rn ALLOW_PRIVATE_IPS apps/monitoring/glitchtip/ returns
nothing, so the shc package does not set it. An in-fabric hookshot URL is
therefore silently dropped with a log line and no user-visible error.
Two postures, and the plug must pick one and say which:
- give hookshot a public ingress host and publish that as
urlBase, the better answer, and the one that also serves any producer outside the fabric; - or set
GLITCHTIP_ALLOW_PRIVATE_IPSon the glitchtip stack, widening its SSRF posture estate-wide, which is an operator’s call and not an edge’s.
VERIFY the default: docker run --rm glitchtip/glitchtip:6.2.5 python -c "from django.conf import settings; print(settings.GLITCHTIP_ALLOW_PRIVATE_IPS)".
The docstring’s phrasing (“when GLITCHTIP_ALLOW_PRIVATE_IPS is False”) reads
as though False is the ordinary case, but that is an inference from prose and
this document does not trade in those.
The plug’s job: GlitchTip has a REST API and an AlertRecipient model
with unique_together = ("alert", "recipient_type", "url"), which makes an
upsert keyed on the URL natural. VERIFY the exact endpoint and auth
(organisation-scoped token vs. session) before writing it; unlike the four
frappe helpers in the WebDAV design, no GlitchTip API surface was read here.
6.2 Wazuh: a custom integration script, which is real work
Section titled “6.2 Wazuh: a custom integration script, which is real work”Measured: the integrator’s built-in name set is slack, pagerduty,
virustotal, shuffle, maltiverse. Anything else is a custom-<name>
executable in /var/ossec/integrations/, owned root:wazuh, invoked with
three arguments: the alert file path, the <api_key> value, and the
<hook_url> value.
So the SHC surface is: an ossec.conf <integration> block naming
custom-shc-webhook, plus a script the image must carry (a bind-mounted
script into /var/ossec/integrations/ is possible, but the ownership and
permission requirements make a baked file the honest answer, and the estate’s
image-owned ruling points the same way).
★ The script’s whole job is to turn a Wazuh alert into {"text": "..."},
which means SHC is now the author of a payload transformer, in Python, inside a
vendor image, with vendor-specified argv. That is not enormous, but it is not
“add a plug” either, and pretending otherwise is how a two-week task gets
estimated at a day.
★★ And note what this means for the whole design: once SHC is writing a
custom- script for Wazuh anyway, that script could POST straight to Matrix’s
client-server API with the matrix socket’s bot token: no bridge, no
appservice, no second stack. §9.1’s phase 0 exists because of this observation.
6.3 GitLab: do not bridge it
Section titled “6.3 GitLab: do not bridge it”GitLab 17.3+ ships a native Matrix integration, Free tier, self-managed included, configurable instance-wide in Admin → Settings → Integrations with hostname + token + room identifier + per-event triggers. shc pins 18.11.7.
Routing GitLab through hookshot would replace per-event trigger selection,
branch filtering and “notify only broken pipelines” with a generic JSON
renderer, and would add a daemon to the path. The right SHC surface for GitLab
is a matrix.plug.yaml on the gitlab package that consumes the existing
matrix socket and drives GitLab’s own integration through its API, the
uptime-kuma shape, one level easier because GitLab has a REST API and Uptime
Kuma did not.
(hookshot does have a first-class GitLab connection type. It is webhook-and-OAuth-coupled, aimed at bridging issues and MRs bidirectionally, and it is a different product than “send alerts to a room”. Out of scope.)
6.4 Uptime Kuma: already done; change nothing
Section titled “6.4 Uptime Kuma: already done; change nothing”apps/monitoring/uptime-kuma/matrix.plug.yaml exists, works, and encodes a
measured idempotency workaround. Touching it to route through a bridge would
be strictly worse.
7. The honest cost of a new packaged app
Section titled “7. The honest cost of a new packaged app”Stated as a list rather than a feeling, because §4.3’s counter-argument deserves a real number to argue with.
| item | what it actually is |
|---|---|
app.yaml | metadata, vars declarations, hooks, health |
compose.yaml | one service, plus a boot script that renders config.yml and registration.yml from vars + socket data; hookshot is file-configured, so this is the matrix package’s shape, not an env-var app |
vars.yaml | homeserver coordinates, listeners, hooks[], hookSecret, permissions[], passkey path |
| the passkey | a 4096-bit RSA key that must exist before first start and survive restarts (§0.1.7). Generated by an init job into a volume, or ref+vault://…?autogen and written at boot. Either way it is per-deployment state |
backup.yaml | the passkey and (if encryption is ever enabled) the crypto store. Connection state lives in Matrix and is covered by the matrix stack’s backup, which is a cross-stack restore-consistency claim and should be stated, not assumed |
tests/tests.bats | the package’s own guards |
| image pin + provenance | ghcr.io/matrix-org/matrix-hookshot at a digest, plus a freshness lane |
| ingress | a public host, if §6.1’s recommended posture is taken |
webhook.socket.yaml | §5, including the derivation and the detection job |
| producer plugs | one per producer that survives §6, today, two |
| the lifecycle | a Node-22-plus-Rust upstream with a release every few weeks (7.4.2 → 7.4.3 → 7.4.4 inside a month), each of which the estate now owns |
★ Two of those are the ones that get underestimated: the boot-script config
render (hookshot is not a twelve-factor app; its configuration is two YAML
files) and the passkey lifecycle (a secret that must be a well-formed RSA
private key, not a random string, which ?autogen does not produce).
8. The exact SHC surfaces, all SPECIFIED
Section titled “8. The exact SHC surfaces, all SPECIFIED”8.1 apps/communication/hookshot/: a new package
Section titled “8.1 apps/communication/hookshot/: a new package”Directory beside matrix under apps/communication/, because that is where
its provider lives and a reader looking for “the Matrix things” should find
both.
matrixAppservice.plug.yaml: required: true (a bridge with no
homeserver is not a degraded bridge, it is nothing), label: hookshot
(informational on this socket, and the handle an operator reads off
shc ls), services: [hookshot].
matrix.plug.yaml: required: false, roomId from
vars.defaultRoom | default(integration.socket.data.defaultRoomId). Bound for
exactly two reasons and the file must say so, because binding a notification
socket to a bridge looks redundant: the room id the static connections
target, and the alerts bot token that issues the invite of §5.4.
compose.yaml: one service, boot script renders:
# registration.yml: hookshot's own copy. Every field is derived from the# matrixAppservice socket, so it agrees with Synapse's copy by construction.# The one field Synapse's copy carries and this one cannot influence is `url`# (§3.2): it is provider policy, and a mismatch there is invisible here and# fatal there.id: "{{ integrations.matrixAppservice.socket.id }}"as_token: "{{ integrations.matrixAppservice.socket.asToken }}"hs_token: "{{ integrations.matrixAppservice.socket.hsToken }}"sender_localpart: "{{ integrations.matrixAppservice.socket.senderLocalpart }}"namespaces: users: [{ regex: "{{ integrations.matrixAppservice.socket.usersRegex }}", exclusive: true }]bridge: domain: "{{ integrations.matrixAppservice.socket.serverName }}" url: "{{ integrations.matrixAppservice.socket.internalHomeserverUrl }}" port: 9993 bindAddress: 0.0.0.0 # NOT the 127.0.0.1 default; Synapse dials inlisteners: - port: 9000 bindAddress: 0.0.0.0 # the sample's 127.0.0.1 default is unreachable in a container resources: [webhooks]passFile: /data/passkey.pempermissions: # MANDATORY; absent grants the whole domain admin - actor: "{{ integrations.matrixAppservice.socket.senderUserId }}" services: [{ service: "*", level: admin }] - actor: "{{ vars.adminMxid }}" services: [{ service: "*", level: admin }]generic: enabled: true urlPrefix: "<public or in-fabric base>/webhook/" allowJsTransformationFunctions: false # the sample calls this unsafe; nothing here needs it enableHttpGet: false # a GET-triggerable bearer URL is a link-preview away from firing includeHookBody: trueconnections: [ … rendered from vars.hooks … ]★ Three of those lines are refusals rather than settings and the file must say
so at each: bindAddress: 0.0.0.0 (twice; the upstream defaults are
127.0.0.1 and unreachable from another container),
allowJsTransformationFunctions: false, and enableHttpGet: false. Every
other service block (github, gitlab, jira, figma, feeds,
openProject, challengeHound, widgets) is omitted, which is how
hookshot disables them (enabledServices in Config.ts derives purely from
which blocks are present).
★ urlPrefix is advertisement, not routing. Measured: the serving path is
/webhook/<hookId> on the webhooks listener regardless of what urlPrefix
says; urlPrefix is what hookshot prints when a user asks it for a URL.
So an in-fabric producer may post to
http://<env>.hookshot.<stack>:9000/webhook/<id> even when urlPrefix names a
public origin. That decoupling is what lets the socket publish an in-fabric
urlBase for colocated producers and a public urlPrefix for everything else.
vars.yaml
hooks: [] # [{name, room}]: the static connections. Read at STARTUP: # adding one is a redeploy, which is why no edge writes it.hookSecret: "ref+vault://hookshot_hook_secret?autogen"adminMxid: "" # a human who may invite the bot and run !hookshot commandsdefaultRoom: "" # empty → the matrix socket's defaultRoomIdjobs: a post_install/post_update hook job (not a plug
post_deployment job: it reads socket values, and consumer plug jobs build
their context from the statically rendered socket data) that
- generates the passkey if absent, asserting it parses as an RSA private key;
- issues and reads back the room invite (§5.4);
- prints, per configured hook, its derived URL, masked in the log to its first 8 characters, because it is a bearer secret.
8.2 apps/communication/hookshot/webhook.socket.yaml
Section titled “8.2 apps/communication/hookshot/webhook.socket.yaml”Per §5.2. service: hookshot. Its jobs.integration is the
detect-and-report job of §5.3; it never writes vars.hooks.
★ Alias-collision check, because this package will grow a second socket.
The engine warns X200931ALICOL only when one hostname resolves to two
different services (ce/modules/app/integration_render.go:1314:
if prior, clash := aliasedBy[hostname]; clash && prior != serviceName). With
one service in this package the pair is safe by construction, and the package
should carry a bats guard asserting every *.socket.yaml in it declares the
same service:, so that a future split into webhooks/metrics containers goes
red in the tree rather than round-robin in DNS.
8.3 Producer surfaces
Section titled “8.3 Producer surfaces”| producer | surface | what it does |
|---|---|---|
| glitchtip | webhook.plug.yaml + a post_deployment job | upserts an AlertRecipient of type webhook on the project alert, keyed on the URL (unique_together makes that natural); refuses with a named cause when the derived URL is private and GLITCHTIP_ALLOW_PRIVATE_IPS is unset (§6.1) |
| wazuh | webhook.plug.yaml + a baked custom-shc-webhook script + an ossec.conf <integration> block | §6.2, and this is the item that is larger than it looks |
| gitlab | matrix.plug.yaml, not webhook | drive GitLab’s own instance-level Matrix integration through its API (§6.3) |
| uptime-kuma | nothing | already wired (§6.4) |
8.4 Guards to add
Section titled “8.4 Guards to add”| test | asserts |
|---|---|
apps/communication/hookshot/tests/tests.bats | the rendered config.yml carries a non-empty permissions: (its absence is a domain-wide admin grant) |
| same | allowJsTransformationFunctions is false and enableHttpGet is false |
| same | no generic.userIdPrefix key is rendered (§3.4: a prefix silently breaks masquerade under the default usersRegex) |
| same | both bindAddress values are 0.0.0.0, never the upstream 127.0.0.1 |
| same | every derived stateKey matches [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} (§5.2, the metrics-redaction constraint) |
| same | every *.socket.yaml in the package declares the same service: |
apps/communication/matrix/tests/tests.bats | unchanged; note only that no guard may assume matrixAppservice has zero consumers |
| producer packages | every socket read is ` |
9. The phased plan
Section titled “9. The phased plan”9.1 ★ Phase 0: the thing that might make phases 1–3 unnecessary
Section titled “9.1 ★ Phase 0: the thing that might make phases 1–3 unnecessary”Before building any of this, build the cheap version and see what is actually missing. Two producers need Matrix (§1.2). Both of them can be reached without a bridge:
- wazuh: the
custom-integration script has to be written either way (§6.2). Written against Matrix’s client-server API with the existingmatrixsocket’s bot token, it is the same script minus a hop. Onematrix.plug.yamlon the wazuh package. - glitchtip: has no Matrix recipient type, so it genuinely needs a
translator. But the translator does not have to be a 7,000-line appservice;
it has to be something that accepts
{"text": …}and callsPUT /_matrix/client/v3/rooms/<id>/send/m.room.message/<txn>.
Deliverables: apps/security/wazuh/matrix.plug.yaml (baked script +
ossec.conf block + a matrix plug), and apps/devops/gitlab/matrix.plug.yaml
(GitLab’s own integration, driven through its API).
What phase 0 buys: three of four producers reaching the room, using a
socket that is already proven by uptime-kuma, with no new package, no new
socket, no appservice, and no new lifecycle. What it leaves: GlitchTip, and
the matrixAppservice socket still at zero consumers.
★ This is stated first because the strongest form of §4.3’s counter-argument is that phase 0 may be the whole answer, and a document that only presents the expensive design has not done its job.
9.2 Phase 1: hookshot, one hook, one room
Section titled “9.2 Phase 1: hookshot, one hook, one room”Gate: phase 0 done, and GlitchTip still unserved (or a second webhook-only producer has appeared).
| # | Deliverable | Where | New? |
|---|---|---|---|
| 1 | vars.appservice.url + enabled set on the matrix stack | operator, §3.2 | no |
| 2 | The hookshot package: app/compose/vars/backup/tests, boot-script config render, passkey lifecycle | apps/communication/hookshot/ | yes, a whole packaged app |
| 3 | matrixAppservice.plug.yaml + matrix.plug.yaml + the invite job | same | no idioms are new |
| 4 | One static connection from vars.hooks, its URL printed masked | same | no |
| 5 | GlitchTip posts to it, by hand (curl) | n/a | no |
Phase 1 ships no socket. The URL is printed and pasted. That is deliberate:
it proves the appservice path end to end (registration loaded, url reachable,
bot joined, static connection live, payload rendered) before any of it is
wrapped in an abstraction, and it is the smallest change that turns
matrixAppservice from argued into proven.
Acceptance (each line a command, not a feeling):
curl -H "Authorization: Bearer <asToken>" <hs>/_matrix/client/v3/account/whoami→ the appservice sender’s mxid.- The hookshot container logs an inbound
PUT /_matrix/app/v1/transactions/…from Synapse within a minute of the invite; this is the only proof thatappservice.urlis right (§3.2). GET /_matrix/client/v3/rooms/<room>/joined_memberslists the appservice sender. A secondshc updatere-issues the invite and reads “is already in the room” as converged, creating nothing.curl -X POST -H 'Content-Type: application/json' -d '{"text":"hello"}' <urlBase>/<stateKey>→ the room showshelloposted by@_shc_appservice:<serverName>, and not by a ghost, which is the §3.4 assertion.- The same POST with a mangled stateKey →
404 {"ok":false,"error":"Webhook not found"}. - A GET to a valid URL →
405, provingenableHttpGet: falsetook. - GlitchTip’s own “send test notification” reaches the room, or fails with “webhook delivery blocked: URL resolves to a private/internal IP” in glitchtip’s log, which is §6.1 settling itself.
9.3 Phase 2: the webhook socket
Section titled “9.3 Phase 2: the webhook socket”The derivation (§5.2), the detect-and-report integration job (§5.3), and the GlitchTip plug. Justified once the URL is being pasted into a second place.
9.4 Phase 3: the things deliberately not built
Section titled “9.4 Phase 3: the things deliberately not built”- Bidirectional bridging. hookshot’s GitHub/GitLab/Jira connections bridge issues and comments back. Different product, different credential lifecycle, different blast radius, and it would make the appservice’s users namespace a live question again.
- Encryption. Needs
cache.redisUri(measured) andvars.appservice.msc4190=trueon the matrix stack, and the matrix package’s own note is blunt about why: “a bridge that has not implemented MSC4190 still tries the legacy login and gets IO.ELEMENT.MSC4190.M_APPSERVICE_LOGIN_UNSUPPORTED.”VERIFYhookshot’s MSC4190 support before turning that flag on; it is a contract, not a fix. - A second registration so two bridges cannot impersonate each other. The
matrix package models one; the extension is named in
matrixAppservice.socket.yamland is real work. - RSS/Atom feeds, Figma, OpenProject. Each is a service block away and each is a separate decision.
10. Remaining unknowns, each with the command that settles it
Section titled “10. Remaining unknowns, each with the command that settles it”Ranked by what they would cost if the assumption is wrong.
2026-08-10: rows 1, 3 and 5 are MEASURED; see §12. Rows 2 and 4 settled as by-products of the same run. Rows 6 and 7 remain open. The ruling-by-ruling readiness map is
docs/proposals/2026-08-10-hookshot-phase0-readiness.md.
| # | Unknown | Settles with | If wrong |
|---|---|---|---|
| 1 | Does Synapse actually push to appservice.url once set? (§3.2) | set it, invite the bot, docker logs <hookshot> for PUT /_matrix/app/v1/transactions/ | the whole bridge is inert while every other check passes, the single highest-cost unknown here |
| 2 | Is GLITCHTIP_ALLOW_PRIVATE_IPS False by default on 6.2.5? (§6.1) | docker run --rm glitchtip/glitchtip:6.2.5 python -c "from django.conf import settings; print(settings.GLITCHTIP_ALLOW_PRIVATE_IPS)" | decides whether hookshot needs a public ingress or glitchtip needs an SSRF widening, a posture decision, not a redesign |
| 3 | Does a static connection materialise without any room state event? (§0.1.3) | render one hook, restart, POST to its URL, expect 200 not 404 | the declarative path collapses to !hookshot webhook <name> chat commands, which are not automatable and would sink the zero-touch story |
| 4 | Does hookshot accept a registration whose sender_localpart is _shc_appservice and whose users namespace is the narrow default? (§3.4) | boot it and watch for a namespace error | a userIdPrefix-free config is the fix and is already the plan; this only checks the plan holds |
| 5 | GlitchTip’s API surface for creating an AlertRecipient (§6.1) | read apps/alerts/ views/routers on 6.2.5 | changes the plug’s job from an API call to something worse; no GlitchTip API surface was read for this document |
| 6 | Is there a provisioning API that beats static connections? (§0.2) | read src/api/ and docs/advanced/ | a phase-2 revision; static connections are sufficient either way |
| 7 | Does hookshot support MSC4190? (§9.4) | grep -rn msc4190 src/ on the pinned version | only gates encryption, which nothing needs yet |
★ And the largest one, stated without hedging: none of this has been built or run. Every hookshot claim above is a source read, not an observation of a running bridge. The upstream reads are exact (line numbers and verbatim comments) and they settle the platform questions. They settle nothing about what happens when the thing boots.
11. Rulings owed
Section titled “11. Rulings owed”-
Is phase 0 the whole answer? (§9.1) Three of four producers reach a Matrix room today through the already-proven
matrixsocket, and the fourth needs a translator, not necessarily a bridge. Building hookshot is defensible; building it first is not. Recommendation: phase 0, then re-ask. -
May the
matrixsocket’s bot token be used to invite? (§5.4) It is the only credential in the estate that can put the appservice into the alerts room without an operator, and the bot created that room so it holds PL 100. It also widens a socket whose stated contract is “post alerts into a room”. Recommendation: yes, with a read-back and a header amendment; the alternative is a documented manual invite, which is a zero-touch failure. -
Where does hookshot live in the tier structure? A Matrix bridge is infrastructure, not a flagship app, and the flagship bar is zero-touch, which §3.2’s two-stack ordering does not meet and cannot be made to meet from the consumer side. That needs saying out loud before it is packaged, not after.
-
Does the estate want a second appservice registration modelled now? (§3.3) With one consumer, sharing is free. The extension is cheap while the matrix package is being touched anyway and expensive later, when a second bridge is blocked on it.
Not owed, because it is decided by measurement: the app omits
generic.userIdPrefix (§3.4: a prefix cannot match the default usersRegex),
every derived stateKey is UUID-shaped (§5.2: the metrics redaction regex),
permissions: is mandatory (§0.1.6; its absence is a domain-wide admin
grant), and GitLab and Uptime Kuma are not routed through the bridge
(§6.3, §6.4). Each of those is a constraint read off code; a design that
contradicts any of them does not work rather than works differently.
12. Evidence appendix: measured 2026-08-10
Section titled “12. Evidence appendix: measured 2026-08-10”§10 warned that every hookshot claim above was a source read, not an
observation of a running bridge. This appendix is the running bridge. A
throwaway lab (matrixdotorg/synapse:v1.158.0 (SQLite) and
ghcr.io/matrix-org/matrix-hookshot:7.4.4 on an isolated Docker network,
plus a 60-line Python stub standing in for the appservice) settled §10 rows
1, 3 and 5, and rows 2 and 4 fell out of the same run. Raw logs, the stub
instrument, and redacted configs are committed beside this document in
evidence/2026-08-10-hookshot-unknowns/; every token below is a sha256
prefix, never a value. The lab was destroyed after capture.
12.1 Row 1: Synapse DOES push to appservice.url. MEASURED, YES.
Section titled “12.1 Row 1: Synapse DOES push to appservice.url. MEASURED, YES.”Two phases, same registration (sender_localpart: _shc_appservice, users
namespace @_shc_[a-z0-9._=+/-]*: non-exclusive, i.e. exactly the matrix
package’s rendered shape from §3), first with url: pointing at the stub,
then at hookshot.
Phase A, stub. Synapse logged Loaded application service: … 'url': 'http://valab-stub:9993', an invite of the bot was issued from an ordinary
user, and the stub received, with no polling, no client sync, nothing but
the registration:
19:27:55 STUB PUT /_matrix/app/v1/transactions/1 auth=bearer(sha256:5cd134947ba6) events=[{m.room.member invite of @_shc_appservice}]19:28:33 STUB PUT /_matrix/app/v1/transactions/2 … events=[{m.room.member join}]19:28:33 STUB PUT /_matrix/app/v1/transactions/3 … events=[{m.room.message "unknown-1 measurement message"}]Arrival was same-second with the client action. And the bearer is worth a
line: its sha256 prefix matches the registration’s hs_token
(5cd134947ba6), not the as_token (4a8db67b937a); Synapse
authenticates itself to the appservice with hs_token, which is the
credential a consumer-side listener would verify.
Phase B, hookshot. The same registration re-pointed at hookshot: Synapse
PUT /_matrix/app/v1/transactions/{1,2,3} → 200, hookshot logged
Processing transaction 1 / Processing event of type m.room.member /
Bot user @_shc_appservice:valab.local joined room. The §3.2 premise (the
whole design’s single highest-cost unknown) holds on a real homeserver.
12.2 Row 3: a static connection materialises with NO room state event. MEASURED, YES.
Section titled “12.2 Row 3: a static connection materialises with NO room state event. MEASURED, YES.”config.yml carried one connections: entry
(uk.half-shot.matrix-hookshot.generic.hook, stateKey
513d8011-6d0d-44f6-b65f-7b6845caa5c4, the alerts room, state: {name: "glitchtip"}) and nothing was ever sent to the room as state. Enumerating
GET /rooms/<room>/state as the room admin returns exactly eight events:
m.room.{create,name,power_levels,join_rules,history_visibility,guest_access}
and two members. Zero uk.half-shot.* state events exist anywhere.
Yet hookshot booted to Bridge is now ready. Found 1 connections, logging
the mechanism in as many words:
Room !QyJFZldCjkbUTJxoBN:valab.local is connected to: GenericHookConnection 513d8011-6d0d-44f6-b65f-7b6845caa5c4 (via static config)POST <urlPrefix>/513d8011-…→202 {"ok":true}and the message arrived in the room as@_shc_appservice(verified from the Synapse side via/messages, not from hookshot’s own log). Note 202, not 200:waitForComplete: falseacknowledges before the Matrix send; the §10 row’s “expect 200 not 404” resolves to the success arm.- Restart persistence: SIGTERM, cold boot,
Found 1 connectionsagain, and a fresh POST landed. The connection needs no state event to survive, either; it is re-derived from config every boot. - Contrast arm:
POST …/webhook/deadbeef-dead-beef-…→404 {"ok":false,"error":"Webhook not found"}. The 202 means something. - One log line deserves disarming:
Room … has no connections and is not an admin roomappears during boot; it refers to state-sourced connections only; the static entry is injected by the ConnectionManager afterwards and the webhook works. Do not let that line fail a health probe.
The declarative path holds. No !hookshot chat command, no provisioning
call, no admin room was involved at any point; the zero-touch story of
§5 survives contact with a running bridge.
12.3 Row 5: GlitchTip 6.2.5’s AlertRecipient surface, read off apps/alerts/ at tag v6.2.5. MEASURED.
Section titled “12.3 Row 5: GlitchTip 6.2.5’s AlertRecipient surface, read off apps/alerts/ at tag v6.2.5. MEASURED.”★ There is no standalone AlertRecipient endpoint. Recipients are nested
in the ProjectAlert resource (apps/alerts/api.py, django-ninja router,
mounted at prefix 0 (glitchtip/api/api.py:58) under path("api/", …),
glitchtip/urls.py:43):
| Verb | Path | Scope required | Line |
|---|---|---|---|
| GET | /api/0/projects/{org_slug}/{project_slug}/alerts/ | project:read|write|admin | api.py:44 |
| POST | /api/0/projects/{org_slug}/{project_slug}/alerts/ → 201 | project:write|admin | api.py:62 |
| PUT | /api/0/projects/{org_slug}/{project_slug}/alerts/{alert_id}/ | project:write|admin | api.py:100 |
| DELETE | /api/0/projects/{org_slug}/{project_slug}/alerts/{alert_id}/ → 204 | project:admin | api.py:149 |
| POST | …/alerts/{alert_id}/test/ | project:write|admin | api.py:172 |
Auth is Authorization: Bearer <token> against APIToken
(glitchtip/api/authentication.py TokenAuth; the model is
apps/api_tokens/models.py:15, 64-char token, BitField scopes). The scope
check (glitchtip/api/permissions.py:21) applies only to token auth;
session auth passes it unconditionally. On top of scopes, the ORM filters
demand the token’s user be org-ADMIN-or-above or a member of one of
the project’s teams for create (api.py:76–85), org-ADMIN for delete.
The payload the plug sends (CamelSchema, camelCase on the wire), for a hookshot generic hook:
{ "name": "shc: matrix bridge", "timespanMinutes": 1, "quantity": 1, "uptime": false, "alertRecipients": [ {"recipientType": "webhook", "url": "https://<hookshot-host>/webhook/<id>"} ]}"webhook" is RecipientType.GENERAL_WEBHOOK (constants.py:9), the
Slack-compatible payload §6.1 already matched to transformHookData.
Upsert semantics favour the plug. PUT does aupdate_or_create keyed on
(alert, recipient_type, url) and deletes recipients absent from the payload
(api.py:126–142); the model’s unique_together ("alert", "recipient_type", "url") (models.py:44) makes the §8 plug table’s “keyed on the URL” upsert
exactly what the API already does.
And §6.1’s “checked twice” claim verifies exactly, with line numbers.
Creation time: WebhookAlertRecipientIn validates the URL through
validate_public_url(allow_private=settings.GLITCHTIP_ALLOW_PRIVATE_IPS)
(schema.py:41–45): a private-IP hookshot URL is rejected at
recipient-creation time with a validation error, so the plug’s
refusal-with-named-cause gets a real API error to surface, not only the
send-time log line to miss. Send time: _is_url_allowed re-checks before
every delivery and session.post(url, allow_redirects=False, …) refuses
redirects (webhooks.py:19–48).
12.4 Rows 2 and 4, settled in passing
Section titled “12.4 Rows 2 and 4, settled in passing”- Row 2:
GLITCHTIP_ALLOW_PRIVATE_IPS = env.bool("GLITCHTIP_ALLOW_PRIVATE_IPS", False):glitchtip/settings.py:304, tag v6.2.5. False by default, from source rather than thedocker runprobe. §6.1’s posture fork is real and the public-ingress arm remains the recommendation. - Row 4: hookshot 7.4.4 booted this exact registration:
sender_localpart: _shc_appservice, the narrow non-exclusive users namespace, nogeneric.userIdPrefix, with no namespace error: bot registered (M_USER_IN_USEon re-boot, i.e. already registered), profile ensured,POST /_matrix/app/v1/ping → 200, bridge ready. All webhook messages were sent as@_shc_appserviceitself, confirming the §3.4 plan: omituserIdPrefix, let the bot be the only puppet.
12.5 What this appendix does NOT settle
Section titled “12.5 What this appendix does NOT settle”Rows 6 (provisioning API vs static connections) and 7 (MSC4190) stay open, and so do all four §11 rulings. Nothing here was run against either estate: the lab was a throwaway Synapse on a private Docker network, created for these measurements and deleted after them.