Skip to content
SHC Docs

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 main in a78b60301 (shipped v0.0.49): apps/communication/hookshot/ exists, webhook.socket.yaml exists, and matrixAppservice now 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, is docs/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.


ClassMeaningMarked
MEASUREDRead off pinned source or vendor docs, 2026-08-09plain statement, with its citation
SPECIFIEDThis document decides it; no code exists”the app MUST…”
VERIFYA concrete assumption with the one command that settles itVERIFY
RULING OWEDAn owner decision, not an agent’s to makeRULING OWED
  1. 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 (Dockerfile stage 0 installs rustup, cmake, libssl-dev). Official image ghcr.io/matrix-org/matrix-hookshot.
  2. It needs a registration with a url, because Synapse must PUSH transactions to it. The matrix package’s vars.appservice.url defaults to "", which its boot script renders as an explicit url: 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.”
  3. ★★ A static connection’s hookId IS its stateKey: src/Connections/GenericHook.ts, the isStatic branch, 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).
  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:
    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;
    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.
  5. ★ With no generic.userIdPrefix, hookshot posts as the appservice bot itself: GenericHookConnection.getUserId():
    if (!this.config.userIdPrefix) { return this.intent.userId; }
    No ghost users, so the matrix package’s narrow default usersRegex needs no widening. §3.4, and §3.4 also shows why the alternative is unavailable.
  6. ★ With no permissions: block, every user on the homeserver domain gets admin over the bridge. src/config/Config.ts:349-352 logs 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 passes checkPermissionAny(sender, BridgePermissionLevel.login).
  7. passFile is mandatory at runtime, not only for OAuth services: src/App/BridgeApp.ts:58 calls UserTokenStore.fromKeyPath(config.passFile, …) unconditionally. It is a 4096-bit RSA private key (openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096).
  8. The inbound path is /webhook/<hookId>: src/Webhooks.ts:77-78 mounts GenericWebhooksRouter at "/webhook" (with a deprecated second copy at /), and src/generic/Router.ts:125 is router.all("/:hookId", …). POST and PUT always; GET only when enableHttpGet is true.
  9. The default body contract is Slack/Mattermost-shaped: transformHookData (GenericHook.ts:674), whose own comment cites Mattermost’s incoming-webhook parameters: a top-level string text becomes the message, a top-level string html becomes the formatted body, anything else is rendered as a fenced JSON block.
  10. matrix has one consumer, not zero. §1.1.

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.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:

Terminal window
ls apps/*/*/matrix.plug.yaml # → apps/monitoring/uptime-kuma/matrix.plug.yaml
ls apps/*/*/matrixAppservice.plug.yaml # → no matches

matrix 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:

producernative Matrix support?evidence
uptime-kumayes, and SHC already wires itapps/monitoring/uptime-kuma/matrix.plug.yaml, consuming the matrix socket’s accessToken + internalHomeserverUrl + roomId
gitlabyes, natively, since 17.3GitLab’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
glitchtipnoapps/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
wazuhnothe 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.


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.yaml to 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, so backup.yaml is 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”

registration.sample.yml, mapped onto what matrixAppservice.socket.yaml publishes:

registration keyhookshot’s samplesocket keyfit
idmatrix-hookshotid (vars.appservice.id, default shc)✓ any unique string
as_tokenrandomasToken@secret!✓
hs_tokenrandomhsToken@secret!✓, and the socket already says the consumer must verify incoming transactions against it
sender_localparthookshotsenderLocalpart (default _shc_appservice)✓ Synapse always lets an appservice act as its own sender_localpart
namespaces.users@_github_.*, @_gitlab_.*, @_webhooks_.*, @feedsusersRegex (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
urlhttp://localhost:9993not published; provider var only★ §3.2, the one real coupling
rate_limitedfalsevars.appservice.rateLimited✓
receive_ephemeraltruenot 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:

Terminal window
shc update <matrix-stack> --var appservice.enabled=true \
--var appservice.url=http://<env>.hookshot.<hookshot-stack>:9993
shc 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/whoami with asToken (the same probe check-appservice-registered already runs); that proves the registration is loaded but says nothing about url;
  • so a second, cheap check: the hookshot stack watches its own :9993 for a Synapse transaction (PUT /_matrix/app/v1/transactions/…). Nothing arriving within a bounded window means url is null or wrong, and the job says so with the exact shc update line 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.

  • vars.appservice.enabled defaults 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.yaml says 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:

optioncost
widen usersRegex on the matrix stack to admit underscoresan operator edit to a security boundary, on the provider, for cosmetics
choose a userIdPrefix with no underscore inside the class, e.g. _shc_whfragile: the suffix is derived from the connection name, which may itself contain characters outside the class
★ omit generic.userIdPrefix entirelyfree, 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”

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”:

  1. Could a second, unrelated implementation serve it? Yes, and there are many: Slack, Mattermost, Rocket.Chat, Discord’s /slack compatibility endpoint, ntfy, and (measured) GlitchTip’s own GENERAL_WEBHOOK producer 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.
  2. Is external-webhook nameable? 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”.

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>
  • hookSecret is 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.
  • ★ uuidshape is not decoration. §0.1.4: the metrics redaction regex matches a v4 UUID and nothing else. Formatting the digest into 8-4-4-4-12 with 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: glitchtip

so 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 the connections: block and, for each, the derived stateKey;

  • the webhook socket’s integration job runs context: service on the hookshot stack per consumer, so it can read integration.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 with
    that 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 provider
    configuration read at startup, and an edge-clocked write would let the last
    consumer 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:

Terminal window
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.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:

@dataclass
class 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_IPS on 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.

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.


Stated as a list rather than a feeling, because §4.3’s counter-argument deserves a real number to argue with.

itemwhat it actually is
app.yamlmetadata, vars declarations, hooks, health
compose.yamlone 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.yamlhomeserver coordinates, listeners, hooks[], hookSecret, permissions[], passkey path
the passkeya 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.yamlthe 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.batsthe package’s own guards
image pin + provenanceghcr.io/matrix-org/matrix-hookshot at a digest, plus a freshness lane
ingressa public host, if §6.1’s recommended posture is taken
webhook.socket.yaml§5, including the derivation and the detection job
producer plugsone per producer that survives §6, today, two
the lifecyclea 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.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 }]
config.yml
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 in
listeners:
- 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.pem
permissions: # 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: true
connections: [ … 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 commands
defaultRoom: "" # empty → the matrix socket's defaultRoomId

jobs: 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

  1. generates the passkey if absent, asserting it parses as an RSA private key;
  2. issues and reads back the room invite (§5.4);
  3. 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.

producersurfacewhat it does
glitchtipwebhook.plug.yaml + a post_deployment jobupserts 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)
wazuhwebhook.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
gitlabmatrix.plug.yaml, not webhookdrive GitLab’s own instance-level Matrix integration through its API (§6.3)
uptime-kumanothingalready wired (§6.4)
testasserts
apps/communication/hookshot/tests/tests.batsthe rendered config.yml carries a non-empty permissions: (its absence is a domain-wide admin grant)
sameallowJsTransformationFunctions is false and enableHttpGet is false
sameno generic.userIdPrefix key is rendered (§3.4: a prefix silently breaks masquerade under the default usersRegex)
sameboth bindAddress values are 0.0.0.0, never the upstream 127.0.0.1
sameevery 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)
sameevery *.socket.yaml in the package declares the same service:
apps/communication/matrix/tests/tests.batsunchanged; note only that no guard may assume matrixAppservice has zero consumers
producer packagesevery socket read is `

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 existing matrix socket’s bot token, it is the same script minus a hop. One matrix.plug.yaml on 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 calls PUT /_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.

Gate: phase 0 done, and GlitchTip still unserved (or a second webhook-only producer has appeared).

#DeliverableWhereNew?
1vars.appservice.url + enabled set on the matrix stackoperator, §3.2no
2The hookshot package: app/compose/vars/backup/tests, boot-script config render, passkey lifecycleapps/communication/hookshot/yes, a whole packaged app
3matrixAppservice.plug.yaml + matrix.plug.yaml + the invite jobsameno idioms are new
4One static connection from vars.hooks, its URL printed maskedsameno
5GlitchTip posts to it, by hand (curl)n/ano

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):

  1. curl -H "Authorization: Bearer <asToken>" <hs>/_matrix/client/v3/account/whoami → the appservice sender’s mxid.
  2. The hookshot container logs an inbound PUT /_matrix/app/v1/transactions/… from Synapse within a minute of the invite; this is the only proof that appservice.url is right (§3.2).
  3. GET /_matrix/client/v3/rooms/<room>/joined_members lists the appservice sender. A second shc update re-issues the invite and reads “is already in the room” as converged, creating nothing.
  4. curl -X POST -H 'Content-Type: application/json' -d '{"text":"hello"}' <urlBase>/<stateKey> → the room shows hello posted by @_shc_appservice:<serverName>, and not by a ghost, which is the §3.4 assertion.
  5. The same POST with a mangled stateKey → 404 {"ok":false,"error":"Webhook not found"}.
  6. A GET to a valid URL → 405, proving enableHttpGet: false took.
  7. 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.

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) and vars.appservice.msc4190=true on 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.” VERIFY hookshot’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.yaml and 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.

#UnknownSettles withIf wrong
1Does 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
2Is 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
3Does a static connection materialise without any room state event? (§0.1.3)render one hook, restart, POST to its URL, expect 200 not 404the declarative path collapses to !hookshot webhook <name> chat commands, which are not automatable and would sink the zero-touch story
4Does 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 errora userIdPrefix-free config is the fix and is already the plan; this only checks the plan holds
5GlitchTip’s API surface for creating an AlertRecipient (§6.1)read apps/alerts/ views/routers on 6.2.5changes the plug’s job from an API call to something worse; no GlitchTip API surface was read for this document
6Is 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
7Does hookshot support MSC4190? (§9.4)grep -rn msc4190 src/ on the pinned versiononly 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.


  1. Is phase 0 the whole answer? (§9.1) Three of four producers reach a Matrix room today through the already-proven matrix socket, 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.

  2. May the matrix socket’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.

  3. 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.

  4. 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: false acknowledges before the Matrix send; the §10 row’s “expect 200 not 404” resolves to the success arm.
  • Restart persistence: SIGTERM, cold boot, Found 1 connections again, 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 room appears 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):

VerbPathScope requiredLine
GET/api/0/projects/{org_slug}/{project_slug}/alerts/project:read|write|adminapi.py:44
POST/api/0/projects/{org_slug}/{project_slug}/alerts/ → 201project:write|adminapi.py:62
PUT/api/0/projects/{org_slug}/{project_slug}/alerts/{alert_id}/project:write|adminapi.py:100
DELETE/api/0/projects/{org_slug}/{project_slug}/alerts/{alert_id}/ → 204project:adminapi.py:149
POST…/alerts/{alert_id}/test/project:write|adminapi.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).

  • 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 the docker run probe. §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, no generic.userIdPrefix, with no namespace error: bot registered (M_USER_IN_USE on re-boot, i.e. already registered), profile ensured, POST /_matrix/app/v1/ping → 200, bridge ready. All webhook messages were sent as @_shc_appservice itself, confirming the §3.4 plan: omit userIdPrefix, let the bot be the only puppet.

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.