Skip to content

Hookshot - Webhooks & Feeds in Matrix Rooms

Matrix-hookshot bridges external services into Matrix rooms. Currently supported integrations:

  • GitLab: Push, merge request, issue, pipeline events from gitlab.com and codebase.helmholtz.cloud
  • Generic webhooks: Any service that can send an HTTP POST
  • RSS/Atom feeds: Periodic polling and posting of new items
  • Outbound webhooks: Forward Matrix messages to an external URL

Unencrypted rooms required

Hookshot cannot operate in end-to-end encrypted rooms yet because end-to-bridge encryption is not compatible with the Matrix Authentication Service (MAS) currently in use (see also [1], [2]). Always use an unencrypted room for Hookshot integrations.

Initial room setup

  1. Create a new unencrypted room (encryption must be disabled at creation time - it cannot be changed afterwards).
  2. Invite the bot: @hookshot:helmholtz.cloud
  3. Give the bot Moderator power level (PL 50) - required for the bot to manage room state.
  4. Send !hookshot help to confirm the bot is responding.

GitLab

Authenticate with GitLab

You can authenticate with GitLab by supplying a Personal Access Token (Scope api). Start a direct conversation with @hookshot:helmholtz.cloud bot and send the generated token to the bridge by saying:

1
gitlab personaltoken <instanceName> <accessToken>

You can check the status at any time by saying:

1
gitlab hastoken <instanceName>

Connect a project

Inside the room, send the command:

1
!hookshot gitlab project https://codebase.helmholtz.cloud/<group>/<project>

Hookshot confirms with Room configured to bridge <group>/<project>.

Register the webhook in GitLab

If you have Maintainer permissions or greater on the GitLab project, the bot will automatically provision the webhook for you.

Otherwise, you’ll need to manually configure the project with a webhook. Go to your GitLab project: Settings > Webhooks > Add new webhook

Field Value
URL https://synapse.matrix.helmholtz.cloud/hookshot/webhooks
Secret token Ask a Matrix admin via support@hifis.net
Triggers Push, MR, issues, pipeline, and other events
SSL verification Enabled

Save, then use the Test button to send a test event.

Remove a connection

Remove the GitLab connection via the configuration widget:

  1. Send the command !hookshot setup-widget in the room
  2. Enter the room info
  3. Select Extensions
  4. Select Hookshot Configuration
  5. Select GitLab Projects

RSS/Atom feeds

Subscribe

1
!hookshot feed <url>

Example:

1
!hookshot feed https://hifis.net/feed/news.xml

Hookshot polls the feed every 10 minutes and posts new items to the room.

List subscriptions

1
!hookshot feed list

Unsubscribe

1
!hookshot feed remove <url>

Generic webhooks

Generic webhooks give each connection its own unique URL. No shared secret is needed - treat the URL itself as a secret.

Create a webhook

1
!hookshot webhook <name> [liveDuration]

Examples:

1
2
!hookshot webhook my-ci-alerts
!hookshot webhook temp-hook 30d

Hookshot responds with a unique URL of the form:

1
https://synapse.matrix.helmholtz.cloud/hookshot/webhooks/webhook/<random-id>

Enter this URL in the external service as the webhook target. When the service sends a POST request to it, the payload appears as a message in the room.

List webhooks

1
!hookshot webhook list

Remove a webhook

1
!hookshot webhook remove <name>

Outbound webhooks

Forward messages posted in the room to an external HTTP endpoint:

1
!hookshot outbound-hook <name> <url>

Configuration widget

For a graphical overview of all active connections in a room:

1
!hookshot setup-widget

This opens the Hookshot configuration widget inside Element. Use it to inspect and remove any type of connection (including GitLab connections, which have no chat-based remove command).