Announce Hookshot webhooks serving at a {prefix}/webhook/:hookId path

Related to 4704a60718

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1681

CHANGELOG.md

@@ -1,3 +1,23 @@
+# 2024-06-25
+
+## The URL-prefix for Hookshot generic webhooks has changed
+
+Until now, generic Hookshot webhook URLs looked like this: `https://matrix.DOMAIN/hookshot/webhooks/:hookId`.
+
+The `/hookshot/webhooks` common prefix gets stripped by Traefik automatically, so Hookshot only sees the part that comes after (`/:hookId`).
+
+[A few years ago](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1681), Hookshot started to prefer to handle webhooks at a `/webhook/:hookId` path (instead of directly at `/:hookId`).
+
+To avoid future problems, we've [reconfigured](https://github.com/spantaleev/matrix-docker-ansible-deploy/commit/4704a60718946fd469aeee7fc3ae8127c633bb6b) our Hookshot configuration to use webhook URLs that include `/webhook` in the URL suffix (e.g. `/hookshot/webhooks/webhook/:hookId`, instead of `/hookshot/webhooks/:hookId`). This means that when we strip the common prefi (`/hookshot/webhooks`), we'll end up sending `/webhook/:hookId` to Hookshot, just like recommended.
+
+When generating new webhooks, you should start seeing the new URLs being used.
+
+**For now**, **both** old URLs (`/hookshot/webhooks/:hookId`) and new URLs (`/hookshot/webhooks/webhook/:hookId`) **continue to work***, so your webhooks will not break just yet.
+
+However, **we recommend that you update all your old webhook URLs** (configured in other systems) to include the new `/webhook` path component, so that future Hookshot changes (whenever they come) will not break your webhooks. You don't need to do anything on the Hookshot side - you merely need to reconfigure the remote systems that use your webhook URLs.
+
+
+
 # 2024-06-22
 
 ## The maubot user is now managed by the playbook

docs/configuring-playbook-bridge-hookshot.md

@@ -50,7 +50,8 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
 
 | listener | default path | variable | used as |
 |---|---|---|---|
-| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", GitLab "URL", etc. |
+| - | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
+| generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
 | github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
 | jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
 | figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |

roles/custom/matrix-bridge-hookshot/defaults/main.yml

@@ -34,7 +34,11 @@ matrix_hookshot_public_scheme: https
 matrix_hookshot_public_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_hookshot_public_endpoint: /hookshot
 
-matrix_hookshot_urlprefix: "{{ matrix_hookshot_public_scheme }}://{{ matrix_hookshot_public_hostname }}{{ matrix_hookshot_public_endpoint }}"
+# This is the base URL prefix shared among all endpoints.
+#
+# It intentionally does not include the path prefix (`matrix_hookshot_public_endpoint`),
+# because of how it's used - it's concatenated with paths that already use matrix_hookshot_public_endpoint` within them.
+matrix_hookshot_urlprefix: "{{ matrix_hookshot_public_scheme }}://{{ matrix_hookshot_public_hostname }}"
 
 # There is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
 matrix_hookshot_appservice_port: 9993
@@ -150,7 +154,7 @@ matrix_hookshot_jira_oauth_redirect_uri: "{{ matrix_hookshot_urlprefix }}{{ matr
 matrix_hookshot_generic_enabled: true
 matrix_hookshot_generic_enableHttpGet: false  # noqa var-naming
 # Default value of matrix_hookshot_generic_endpoint: "/hookshot/webhooks"
-matrix_hookshot_generic_endpoint: "{{ matrix_hookshot_webhook_endpoint }}"
+matrix_hookshot_generic_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/webhook"
 # urlprefix gets updated with protocol & port in group_vars/matrix_servers
 matrix_hookshot_generic_urlPrefix: "{{ matrix_hookshot_urlprefix }}{{ matrix_hookshot_generic_endpoint }}"  # noqa var-naming
 # If you're also using matrix-appservice-webhooks, take care that these prefixes don't overlap
@@ -249,7 +253,7 @@ matrix_hookshot_container_labels_webhooks_traefik_entrypoints: "{{ matrix_hooksh
 matrix_hookshot_container_labels_webhooks_traefik_tls: "{{ matrix_hookshot_container_labels_webhooks_traefik_entrypoints != 'web' }}"
 matrix_hookshot_container_labels_webhooks_traefik_tls_certResolver: "{{ matrix_hookshot_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
 
-# Controls whether labels will be added that expose Hookshot's generic endpoint
+# Controls whether labels will be added that expose Hookshot's appservice endpoint
 matrix_hookshot_container_labels_appservice_enabled: true
 matrix_hookshot_container_labels_appservice_traefik_rule: "Host(`{{ matrix_hookshot_appservice_hostname }}`) && PathPrefix(`{{ matrix_hookshot_appservice_endpoint }}`)"
 matrix_hookshot_container_labels_appservice_traefik_priority: 0