DOCSEARCHbyAlgolia
Submit Docs

Matrix Hookshot Documentation

repository·main·Indexed 19 days ago

https://github.com/matrix-org/matrix-hookshot

A Matrix bot that bridges Matrix rooms with external services including GitHub, GitLab, Jira, OpenProject, Figma, Challenge Hound, and RSS/Atom feeds. It supports end-to-bridge encryption, generic webhooks with JavaScript templates, and uses Matrix state for persistence instead of an external database. The documentation covers installation via Helm and Docker Compose, configuration of service bots, encryption setup, and experimental multi-process worker mode using Redis.

Tokens
37.6K
Snippets
126
Records
174
Agent score
66%

What's inside Matrix Hookshot

  1. Overview of Matrix Hookshot

    main

    Matrix Hookshot is a Matrix bot designed to connect Matrix rooms to external services such as GitHub, GitLab, JIRA, and more.

    Key features include:

    • Out-of-the-box integrations: Support for several popular services.
    • Generic Webhooks: Ability to connect any service using JavaScript-based rich templates.
    • No external database: Uses Matrix state as a persistent store, simplifying deployment.
    • End-to-Bridge encryption: Supports usage within encrypted Matrix rooms.
    • Powerful widgets: Configuration can be managed directly from a Matrix room or via the Element Extensions Store.

  2. How workers and multi-process mode work in Hookshot

    main

    Hookshot supports a worker configuration that allows running the service in multi-process mode. In this mode, Redis acts as the middleman process to handle traffic and communication between different service processes.

    Warning: This feature is experimental and should only be used when the monolith process reaches its natural performance limits.

  4. How Hookshot Connections work

    main

    Hookshot operates using Connections. A single Matrix room can have multiple connections to different external services (e.g., GitHub, Jira).

    Connections are defined within the room state and specify:

    1. The service being connected to.
    2. The type of integration (e.g., a specific GitHub repository or a Jira project).
    3. Any additional configuration required for that specific integration.

    The specific connection types available to a room depend on the configuration provided to the Hookshot service during its own setup.

  5. Use JavaScript Transformations for Webhooks

    main

    JavaScript transformations allow you to write custom logic to parse incoming webhook payloads and generate specific Matrix messages. This feature must be enabled via allowJsTransformationFunctions: true in the generic config.

    Implementation Details

    • Execution: Scripts run in a sandboxed JavaScript VM with a 2-second execution limit.
    • Input: The data variable contains the parsed request body.
    • Output: You must set the result variable.
    • Editing: Scripts are edited by modifying the Matrix state event of type uk.half-shot.matrix-hookshot.generic.hook under the transformationFunction key.

    API Versions

    • V1 API: result must be a string. It is treated as Markdown and prefixed with Received webhook:.
    • V2 API: result must be an object (see schema below).

  6. Manage user permissions and service access

    main

    Hookshot uses a fine-grained permission system to control which users (actors) can access specific services. Permissions are additive; a higher level grants all permissions of the levels below it.

    Actors

    An actor can be:

    • A MxID (e.g., "@user:domain.com" — must be quoted)
    • A homeserver domain (e.g., matrix.org)
    • A roomId (e.g., "!roomId:domain.com" — must be quoted)
    • "*" (matches all users)

    Service Levels

    • commands: Run commands in rooms, but cannot log in.
    • login: All above, plus ability to log in to supported networks (GitHub, GitLab, etc.). Minimum level required to invite the bridge to rooms.
    • notifications: All above, plus bridging notifications (GitHub only).
    • manageConnections: All above, plus ability to create/delete connections.
    • admin: All permissions, including administrative tasks like deleting connections from all rooms.

    Supported Services

    github, gitlab, jira, feed, figma, generic (formerly webhooks), openproject, challengehound, or * for all.

    permissions:
  - actor: "@alice:example.com"
    services:
      - service: "*"
        level: admin
  - actor: "example.com"
    services:
      - service: github
        level: manageConnections

  7. Understand Inbound Webhook Payload Handling

    main

    Hookshot transforms HTTP payloads into Matrix messages based on the request body content:

    Default Mapping

    • text key: Used as the message body (body). Automatically converted from Markdown to HTML.
    • html key: Used as the formatted message body (formatted_body). A text key must still be provided as a fallback.
    • username key: If present, this string is prepended to both the text and html bodies.
    • No text key: If the body lacks a text field, the full payload is sent to the room (this can be customized via JavaScript transformations).

    Supported Content-Types

    Hookshot decodes the following formats in order:

    1. XML: When Content-Type ends in /xml or +xml.
    2. Web form data: When Content-Type is application/x-www-form-urlencoded.
    3. JSON: When Content-Type is application/json.
    4. Text: When Content-Type begins with text/.

    Data Storage

    The full raw request body is stored inside the Matrix event under the key uk.half-shot.hookshot.webhook_data. Note that JSON floating-point values are converted to strings in this field to comply with Matrix specifications.

  8. Configure Static Connections in Hookshot

    main

    Hookshot supports "static connections," which allow system administrators to define a pre-specified set of connections that cannot be altered at runtime. These connections provide predictable configuration without requiring any interaction with the Matrix protocol.

    Note that not all connection types are currently suitable for static configuration.

  9. Authenticate with OpenProject via OAuth

    main

    OpenProject authentication requires OAuth support to be configured in your config.yml and accessible from the internet. This is required for bridging OpenProject into rooms.

    1. In a DM room with the Hookshot bot, send: openproject login.
    2. Click the unique URL generated by the bot.
    3. Follow the authentication steps.

    Note: Authentication may also be available via a widget if configured.

    openproject login

  10. Requirements for Matrix Hookshot

    main

    Before installing Matrix Hookshot, ensure you meet the following requirements:

    • Administrative Access: You must have administrative access to an existing Matrix homeserver to configure the appservice registration.
    • Memory: Hookshot is lightweight and can run with as little as 100 MB of memory, though requirements may increase based on traffic and the number of bridged rooms.

  11. Configure the ChallengeHound bridge

    main

    To bridge ChallengeHound activities into Matrix, you must provide an API token in your Hookshot configuration. You can obtain this token by emailing ChallengeHound support (they typically provide one to challenge admins).

    Add the following to your configuration file:

    challengeHound:
  token: <the token>

  12. Set up the Figma bridge

    main

    To bridge Figma webhooks with Hookshot, you must meet the following requirements:

    1. Figma Account: Must be on the professional tier (the free tier does not provide webhook access).
    2. Personal Access Token: A token with admin access to the target team.
    3. Team ID: Found in the URL of your Figma team page (e.g., 12345 in https://www.figma.com/files/team/12345/...).