Matrix Hookshot

https://matrix-org.github.io/matrix-hookshot/latest/
Admin
Matrix Hookshot is a Matrix bot that connects external services like GitHub, GitLab, JIRA, Figma,...
Tokens:25,380
Snippets:359
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Comprehensive Bridge Permissions Setup

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

A detailed configuration example demonstrating various permission scenarios, including global command access, room-specific management, domain-based logins, and user-specific administrative rights.

```yaml
permissions:
  # Allow all users to send commands to existing services
  - actor: "*"
    services:
      - service: "*"
        level: commands
  # Allow any user that is part of this space to manage github connections
  - actor: "!TlZdPIYrhwNvXlBiEk:half-shot.uk"
    services:
      - service: github
        level: manageConnections
  # Allow users on this domain to log in to jira and github.
  - actor: support.example.com
    services:
      - service: jira
        level: login
      - service: github
        level: commands
  # Allow users on this domain to enable notifications on any service.
  - actor: engineering.example.com
    services:
      - service: "*"
        level: notifications
  # Allow users on this domain to create connections.
  - actor: management.example.com
    services:
      - service: "*"
        level: manageConnections
  # Allow this specific user to do any action
  - actor: "@alice:example.com"
    services:
      - service: "*"
        level: admin
```

--------------------------------

### Docker Compose Setup for Hookshot Development

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

This command initiates the Hookshot development environment using Docker Compose. Ensure Docker Compose is installed and the project repository is checked out.

```bash
docker compose up
```

--------------------------------

### Clone and Install Hookshot

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Clone the Hookshot repository and install its dependencies using Yarn or npm. Ensure Node.js and Rust are installed beforehand.

```bash
git clone https://github.com/matrix-org/matrix-hookshot.git
cd matrix-hookshot
yarn # or npm i
```

--------------------------------

### Build Hookshot Documentation

Source: https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html

Instructions for building the documentation locally using mdbook. Ensure mdbook is installed before running these commands.

```bash
cargo install mdbook
mdbook build
sensible-browser book/index.html
```

--------------------------------

### Configure Generic Hook Connection

Source: https://matrix-org.github.io/matrix-hookshot/latest/usage/static_connections.html

Example configuration for a generic inbound webhook. This allows for static setup of webhooks that can be activated by sending requests to a specific URL.

```yaml
connections:
 - connectionType: uk.half-shot.matrix-hookshot.generic.hook
   stateKey: id-used-by-webhook
   roomId: "!any-room-id:example.org"
   state:
     name: My static hook
     # All below are optional
     waitForComplete: true
     includeHookBody: true
     expirationDate: 2025-11-03T16:44:59.533Z
     transformationFunction: |
        result = {
            plain: "*Everything is fine*",
            version: "v2",
        };

```

--------------------------------

### Hookshot Bridge Configuration Example

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Configure Hookshot's connection details to the Matrix homeserver. Ensure the bind address is '0.0.0.0' for Docker deployments.

```yaml
bridge:
  domain: example.com # The homeserver's server name.
  url: http://localhost:8008 # The URL where Hookshot can reach the client-server API.
  mediaUrl: https://example.com # Optional. The url where media hosted on the homeserver is reachable (this should be publically reachable from the internet)
  port: 9993 # The port where hookshot will listen for appservice requests.
  bindAddress: 127.0.0.1 # The address which Hookshot will bind to. Docker users should set this to `0.0.0.0`.
```

--------------------------------

### Build and Run Hookshot Locally

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

After making changes to the Hookshot code, use these commands to build the project and start the application. This is part of the local development workflow.

```bash
yarn build
yarn start
```

--------------------------------

### Webhook Handling with GET Requests

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Enable webhooks to be triggered by GET requests in addition to POST and PUT. Query parameters will be used as the request body for GET requests.

```text
Hookshot handles HTTP requests with a method of `GET`, `POST` or `PUT`.
If the request is a `GET` request, the query parameters are assumed to be the body.

```

--------------------------------

### Start Hookshot in Production Mode

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Run the Hookshot bridge in production mode for better performance. Set the NODE_ENV environment variable to 'production'.

```bash
NODE_ENV=production yarn start
```

--------------------------------

### Configure OpenProject Integration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/openproject.html

Set the OpenProject integration details in your bridge configuration file. Ensure the baseUrl, webhook secret, and OAuth credentials match your OpenProject setup.

```yaml
openProject:
  baseUrl: https://your-open-project.com
  webhook:
    secret: secrettoken
  oauth:
    clientId: foo
    clientSecret: bar
    redirectUri: https://example.com/oauth/
```

--------------------------------

### Example JSON Log Output Schema

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Illustrates the structure of JSON logs when the 'json' option is enabled. Includes fields for level, message, module, timestamp, and optional error details.

```json
{
  // The level of the log.
  level: "WARN",
  // The log message.
  message: "Failed to connect to homeserver",
  // The module which emitted the log line.
  module: "Bridge",
  // The timestamp of the log line.
  timestamp: "11:45:02:198",
  // Optional error field, if the log includes an Error
  error: "connect ECONNREFUSED 127.0.0.1:8008",
  // Additional context, possibly including the error body.
  args: [
    {
      address: "127.0.0.1",
      code: "ECONNREFUSED",
      errno: -111,
      port: 8008,
      syscall: "connect",
    },
    "retrying in 5s",
  ],
}
```

--------------------------------

### Nginx Proxy Configuration for Widget API

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Example Nginx configuration to proxy requests to the widget API endpoint to the Hookshot backend.

```nginx
location ~ ^/widgetapi(.*)$ {
    set $backend "127.0.0.1:9002";
    proxy_pass http://$backend/widgetapi$1$is_args$args;
}

```

--------------------------------

### JSON Log Schema Example

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

An example of the structured JSON log format, including fields for level, message, module, timestamp, and optional error details.

```json
{
  // The level of the log.
  level: "WARN",
  // The log message.
  message: "Failed to connect to homeserver",
  // The module which emitted the log line.
  module: "Bridge",
  // The timestamp of the log line.
  timestamp: "11:45:02:198",
  // Optional error field, if the log includes an Error
  error: "connect ECONNREFUSED 127.0.0.1:8008",
  // Additional context, possibly including the error body.
  args: [
    {
      address: "127.0.0.1",
      code: "ECONNREFUSED",
      errno: -111,
      port: 8008,
      syscall: "connect",
    },
    "retrying in 5s",
  ],
}

```

--------------------------------

### Nginx Configuration for Widget API

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Example Nginx configuration to proxy requests for the widget API to the Hookshot backend. Ensure the backend address and port match your Hookshot listener configuration.

```nginx
location ~ ^/widgetapi(.*)$ {
    set $backend "127.0.0.1:9002";
    proxy_pass http://$backend/widgetapi$1$is_args$args;
}
```

--------------------------------

### Example Permissions for GitHub Access

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Grants specific users and domains different levels of access to GitHub. Note that higher permissions granted to an actor override explicitly lower ones.

```yaml
permissions:
  - actor: example.com
    services:
      - service: GitHub
        level: manageConnections
  - actor: "@badapple:example.com"
    services:
      - service: GitHub
        level: login
```

--------------------------------

### Generic Webhook Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configure generic webhook settings, including enabling inbound and outbound support, setting a URL prefix, and controlling JavaScript transformation functions and HTTP GET requests.

```yaml
generic:
  enabled: true
  outbound: true # For outbound webhook support
  urlPrefix: https://example.com/mywebhookspath/
  allowJsTransformationFunctions: false
  waitForComplete: false
  enableHttpGet: false
  # maxExpiryTime: 30d
  # sendExpiryNotice: false
  # userIdPrefix: webhook_

```

--------------------------------

### Synapse Error Logs for Connection Issues

Source: https://matrix-org.github.io/matrix-hookshot/latest/troubleshooting.html

Example error logs from Synapse indicating that the homeserver cannot reach the application service. These logs often point to networking problems or incorrect URL configurations.

```log
synapse.http.client - 422 - INFO - as-recoverer-339 - Error sending request to  PUT http://yourhookshoturl/_matrix/app/v1/transactions/123: ConnectionRefusedError Connection refused
synapse.appservice.api - 405 - WARNING - as-recoverer-339 - push_bulk to http://yourhookshoturl threw exception(ConnectionRefusedError) Connection was refused by other side: 111: Connection refused. args=('Connection refused',)
synapse.appservice.scheduler - 480 - INFO - as-recoverer-339 - Scheduling retries on hookshot in Ns
```

--------------------------------

### Configure Widgets in Hookshot

Source: https://matrix-org.github.io/matrix-hookshot/latest/advanced/widgets.html

This YAML configuration sets up various widget functionalities for Hookshot. It controls whether widgets are added to admin rooms, enables a room setup widget with options for automatic addition on invite, and specifies a public URL for widget content.

```yaml
widgets:
  addToAdminRooms: false
  roomSetupWidget:
    addOnInvite: false
  # disallowedIpRanges:
  #     - 127.0.0.0/8
  #     - 10.0.0.0/8
  #     - 172.16.0.0/12
  #     - 192.168.0.0/16
  #     - 100.64.0.0/10
  #     - 192.0.0.0/24
  #     - 169.254.0.0/16
  #     - 192.88.99.0/24
  #     - 198.18.0.0/15
  #     - 192.0.2.0/24
  #     - 198.51.100.0/24
  #     - 203.0.113.0/24
  #     - 224.0.0.0/4
  #     - ::1/128
  #     - fe80::/10
  #     - fc00::/7
  #     - 2001:db8::/32
  #     - ff00::/8
  #     - fec0::/10
  publicUrl: https://example.com/widgetapi/v1/static
  branding:
    widgetTitle: Hookshot Configuration
  openIdOverrides:
    my-local-server: "http://localhost"

```

--------------------------------

### Start Hookshot Worker Processes

Source: https://matrix-org.github.io/matrix-hookshot/latest/advanced/workers.html

Use yarn to start the individual Hookshot worker processes. All worker types must be started together when running in worker mode.

```bash
yarn start:webhooks
```

```bash
yarn start:matrixsender
```

```bash
yarn start:app
```

--------------------------------

### Run Hookshot using Docker

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Deploy Hookshot using the official Docker image. Map necessary ports and mount a volume for configuration files.

```bash
docker run \
    --name matrix-hookshot \
    -d \
    -p 9993:9993 \
    -p 9000:9000 \
    -p 9002:9002 \
    -v /etc/matrix-hookshot:/data \
    halfshot/matrix-hookshot:latest
```

--------------------------------

### Sample Bridge Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

A placeholder for a complete sample bridge configuration file, which can be modified to alter bridge behavior.

```yaml
# Below is a sample bridge configuration file. The configuration file can be tweaked to change the behaviour of your bridge. A bridge of the server is required to apply any changes made to this file.

```

--------------------------------

### Configure GitHub Service Options

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/github.html

This configuration block sets up the connection options for the GitHub service within Hookshot. Ensure the `enterpriseUrl` is provided for on-premise instances. The `auth` section requires the App ID and a path to the private key file. The `webhook` secret must match the one configured in the GitHub App. OAuth credentials and default room connection options can also be specified.

```yaml
github:
  enterpriseUrl: "https://your-enterprise-address.com"
  auth:
    id: 123
    privateKeyFile: github-key.pem
  webhook:
    secret: secrettoken
  oauth:
    client_id: foo
    client_secret: bar
    redirect_uri: https://example.com/oauth/
  defaultOptions:
    showIssueRoomLink: false

```

--------------------------------

### Validate Hookshot Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Validate the Hookshot configuration file without starting the service. This command checks for syntax errors and completeness.

```bash
yarn validate-config
```

--------------------------------

### Configure Metrics Support

Source: https://matrix-org.github.io/matrix-hookshot/latest/metrics.html

Add this configuration to your config file to enable metrics. Hookshot will then provide metrics on the specified bind address and port.

```yaml
metrics:
  enabled: true
  bindAddress: 127.0.0.1
  port: 9002

```

--------------------------------

### Basic Bridge Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/sample-configuration

Configure the core homeserver details, logging levels, and passkey for token encryption. Ensure the passkey is generated securely.

```yaml
bridge:
  # Basic homeserver configuration
  domain: example.com
  url: http://localhost:8008
  mediaUrl: https://example.com
  port: 9993
  bindAddress: 127.0.0.1
logging:
  # Logging settings. You can have a severity debug,info,warn,error
  level: info
  colorize: true
  json: false
  timestampFormat: HH:mm:ss:SSS
passFile:
  # A passkey used to encrypt tokens stored inside the bridge.
  # Run openssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096 to generate
  ./passkey.pem
```

--------------------------------

### List JIRA Project Connections

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Lists all JIRA project connections for the current room.

```bash
!hookshot jira list project
```

--------------------------------

### Run Hookshot using Docker

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Deploy Hookshot using the official Docker image, mapping necessary ports and volumes for configuration and data persistence.

```bash
docker run \
    --name matrix-hookshot \
    -d \
    -p 9993:9993 # Homeserver port
    -p 9000:9000 # Webhook port
    -p 9002:9002 # Metrics port
    -v /etc/matrix-hookshot:/data \
    halfshot/matrix-hookshot:latest
```

--------------------------------

### OpenProject Integration Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/sample-configuration

Configure OpenProject support, including the base URL, webhook secret, and OAuth client credentials.

```yaml
#openProject:
#  # (Optional) Configure OpenProject support
#  baseUrl: https://your-open-project.com
#  webhook:
#    secret: secrettoken
#  oauth:
#    clientId: foo
#    clientSecret: bar
#    redirectUri: https://example.com/oauth/
```

--------------------------------

### Enable Metrics Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configuration block to enable and set up metrics collection for Hookshot. Metrics will be available at the specified bindAddress and port.

```yaml
metrics:
  enabled: true
  bindAddress: 127.0.0.1
  port: 9002
```

--------------------------------

### JavaScript Transformation API v2 Example

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/webhooks

The v2 API for transformation scripts expects an object to be returned. This object defines the Matrix message content, mentions, and optional webhook responses.

```javascript
{
  "version": "v2", // The version of the schema being returned from the function. This is always "v2".
  "empty": true|false, // Should the webhook be ignored and no output returned. The default is false (plain must be provided).
  "plain": "Some text", // The plaintext value to be used for the Matrix message. 
  "html": "<b>Some</b> text", // The HTML value to be used for the Matrix message. If not provided, plain will be interpreted as markdown.
  "msgtype": "some.type", // The message type, such as m.notice or m.text, to be used for the Matrix message. If not provided, m.notice will be used.
  "mentions": { // Explicitly mention these users, see https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions
    "room": true,
    "user_ids": ["@foo:bar"]
  },
  "webhookResponse": {
    "body": "{ \"ok\": true }",
    "contentType": "application/json",
    "statusCode": 200
  }
}
```

--------------------------------

### Configure Generic Webhooks

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/webhooks

Add this configuration to your `config.yaml` to enable generic webhook support, including outbound webhooks.

```yaml
generic:
  enabled: true
  outbound: true # For outbound webhook support
  urlPrefix: https://example.com/mywebhookspath/
  allowJsTransformationFunctions: false
  waitForComplete: false
  enableHttpGet: false
  # maxExpiryTime: 30d
  # sendExpiryNotice: false
  # userIdPrefix: webhook_
```

--------------------------------

### Configure Logging Options

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Set logging level, format (human-readable or JSON), colorization, and timestamp format. Defaults to 'info' level.

```yaml
logging:
  # Level of information to report to the logs. Can be `debug`, `info`, `warn` or `error.
  level: info
  # Should the logs output in human-readable format or JSON. If you are using a third-party ingestion service like logstash, use this.
  json: false
  # Ignored if `json` is enabled. Should the logs print the levels in color. This will print extra characters around the logs which may not be suitable for some systems.
  colorize: true
  #  Ignored if `json` is enabled. The timestamp format to use in log lines. See https://github.com/taylorhakes/fecha#formatting-tokens for help on formatting tokens.
  timestampFormat: HH:mm:ss:SSS

```

--------------------------------

### Register User Namespaces for Homeserver

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configure the homeserver to allow Hookshot control over specific user namespaces by defining regex patterns and exclusivity.

```yaml
__
- regex: "@feeds:example.com" # Where example.com is your homeserver's domain
  exclusive: true


```

--------------------------------

### Configure GitLab Instances

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/gitlab.html

List all GitLab instances you plan to connect to. This allows users to specify instances with short names. Ensure you generate a unique webhook secret for security.

```yaml
gitlab:
  # (Optional) Configure this to enable GitLab support
  #
  instances:
    gitlab.com:
      url: https://gitlab.com
  webhook:
    secret: secrettoken
    publicUrl: https://example.com/webhooks/

```

--------------------------------

### Configure JIRA Project Connection Options

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Defines options for JIRA project notifications in room state. The `events` option specifies which event types to receive.

```json
{
  "events": ["issue_created", "issue_updated"],
  "commandPrefix": "!jira"
}
```

--------------------------------

### Configure Figma Bridge in config.yml

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/figma.html

Set up the Figma integration in your Hookshot `config.yml`. Ensure `publicUrl` points to your webhooks listener and `accessToken` is a valid Figma personal access token.

```yaml
figma:
  publicUrl: https://example.com/hookshot/
  instances:
    your-instance:
      teamId: your-team-id
      accessToken: your-personal-access-token
      passcode: your-webhook-passcode

```

--------------------------------

### Configure Service Bots in Hookshot

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Set up specialized bot users for different connection types, defining their localpart, display name, avatar, command prefix, and service type.

```yaml
__
serviceBots:
  - localpart: feeds
    displayname: Feeds
    avatar: "./assets/feeds_avatar.png"
    prefix: "!feeds"
    service: feeds


```

--------------------------------

### Enable Redis Cache

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configure Hookshot to use Redis for caching to improve startup times and enable features like feed resumption.

```yaml
cache:
  redisUri: "redis://redis-host:3679"

```

--------------------------------

### Configure GitLab Repository Connection

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Defines options for GitLab repository notifications in room state. Use `enableHooks` to specify desired event types.

```json
{
  "commandPrefix": "!gh",
  "enableHooks": [
    "merge_request",
    "push",
    "release"
  ],
  "excludingLabels": ["bug"],
  "includeCommentBody": true,
  "includingLabels": ["enhancement"],
  "pushTagsRegex": "^v\\d\\.",
  "ignoreHooks": []
}
```

--------------------------------

### Bridge JIRA Project Command

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Command to connect a JIRA project to a Matrix room. Ensure the bot has moderator permissions.

```bash
!hookshot jira project https://jira-instance/.../projects/PROJECTKEY/...
```

--------------------------------

### HTTP Listener Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/sample-configuration

Define HTTP listeners for different resources like webhooks, widgets, and metrics. Ensure each listener uses a unique port and specify the bind address appropriately, especially for Docker environments.

```yaml
listeners:
  # HTTP Listener configuration.
  # Bind resource endpoints to ports and addresses.
  # 'port' must be specified. Each listener must listen on a unique port.
  # 'bindAddress' will default to '127.0.0.1' if not specified, which may not be suited to Docker environments.
  # 'resources' may be any of webhooks, widgets, metrics
  - port: 9000
    bindAddress: 0.0.0.0
    resources:
      - webhooks
  - port: 9001
    bindAddress: 127.0.0.1
    resources:
      - metrics
  - port: 9002
    bindAddress: 0.0.0.0
    resources:
      - widgets
```

--------------------------------

### Configure Hookshot Logging Options

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Set logging level, format (human-readable or JSON), colorization, and timestamp format. The default level is 'info'.

```yaml
logging:
  # Level of information to report to the logs. Can be `debug`, `info`, `warn` or `error.
  level: info
  # Should the logs output in human-readable format or JSON. If you are using a third-party ingestion service like logstash, use this.
  json: false
  # Ignored if `json` is enabled. Should the logs print the levels in color. This will print extra characters around the logs which may not be suitable for some systems.
  colorize: true
  #  Ignored if `json` is enabled. The timestamp format to use in log lines. See https://github.com/taylorhakes/fecha#formatting-tokens for help on formatting tokens.
  timestampFormat: HH:mm:ss:SSS
```

--------------------------------

### Configure User ID Prefix for Webhooks

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/webhooks

If you use `userIdPrefix`, configure your `registration.yaml` to include the generated user IDs.

```yaml
# registration.yaml
---
namespaces:
  users:
    - regex: "@webhook_.+:example.com" # Where example.com is your domain name.
      exclusive: true

```

--------------------------------

### Configure Widget Listener

Source: https://matrix-org.github.io/matrix-hookshot/latest/advanced/widgets.html

This YAML configuration defines a listener for the widgets resource on port 5069, binding to all available network interfaces. This is necessary for Hookshot to serve widget content.

```yaml
listeners:
  - port: 5069
    bindAddress: 0.0.0.0
    resources:
      - widgets

```

--------------------------------

### Configure Listeners for Widgets

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Define network listeners for Hookshot, specifying the port, bind address, and the resources to be served, such as widgets.

```yaml
__
listeners:
  - port: 5069
    bindAddress: 0.0.0.0
    resources:
      - widgets


```

--------------------------------

### Figma Integration Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/sample-configuration

Configure Figma support by providing a public URL and instance-specific details like team ID, access token, and webhook passcode.

```yaml
#figma:
#  # (Optional) Configure this to enable Figma support
#  publicUrl: https://example.com/hookshot/
#  instances:
#    your-instance:
#      teamId: your-team-id
#      accessToken: your-personal-access-token
#      passcode: your-webhook-passcode
```

--------------------------------

### Jira On-Premise Configuration with OAuth

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/jira.html

Configure Jira URL, webhook secret, OAuth consumer key, private key path, and redirect URI for on-premise Jira instances in `config.yml`.

```yaml
jira:
  url: https://yourjirainstance.com # The location of your jira instance.
  webhook:
    # A secret string generated by you.
    secret: Ieph7iecheiThoo1othaineewieSh1koh2chainohtooyoh4waht1oetoaSoh6oh
  oauth:
    # Another secret key generated by you.
    consumerKey: secret-consumer-key
    # Path to a private key. Generate this with `openssl genrsa -out jira_privatekey.pem 4096`
    privateKey: jira_privatekey.pem
    # The path to your webhooks listener on the "/jira/oauth" path.
    redirect_uri: http://localhost:5065/jira/oauth
```

--------------------------------

### GitHub Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configure GitHub integration, including enterprise URL, authentication details, webhook secret, OAuth credentials, and default options. Ensure private key file path is correct for Docker users.

```yaml
__
github:
  enterpriseUrl: "https://your-enterprise-address.com"
  auth:
    id: 123
    privateKeyFile: github-key.pem
  webhook:
    secret: secrettoken
  oauth:
    client_id: foo
    client_secret: bar
    redirect_uri: https://example.com/oauth/
  defaultOptions:
    showIssueRoomLink: false


```

--------------------------------

### Configure Figma Webhook Instance

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Define a Figma instance with its `teamId`, `accessToken`, and a `passcode` for webhook authentication. The `publicUrl` must point to the webhook listener endpoint.

```yaml
figma:
  publicUrl: https://example.com/hookshot/
  instances:
    your-instance:
      teamId: your-team-id
      accessToken: your-personal-access-token
      passcode: your-webhook-passcode
```

--------------------------------

### GitLab Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/print.html

Configure GitLab integration, specifying instances, webhook secret, and public URL. Ensure the webhook secret matches the 'Secret token' in GitLab and the public URL points to the correct webhook listener path.

```yaml
__
gitlab:
  # (Optional) Configure this to enable GitLab support
  #
  instances:
    gitlab.com:
      url: https://gitlab.com
  webhook:
    secret: secrettoken
    publicUrl: https://example.com/webhooks/


```

--------------------------------

### GitLab Integration Configuration

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup/sample-configuration

Enable GitLab support by configuring instances, webhook secrets, public URLs, and user ID prefixes. The comment debounce time can also be adjusted.

```yaml
#gitlab:
#  # (Optional) Configure this to enable GitLab support
#  instances:
#    gitlab.com:
#      url: https://gitlab.com
#  webhook:
#    secret: secrettoken
#    publicUrl: https://example.com/hookshot/
#  userIdPrefix:
#    # (Optional) Prefix used when creating ghost users for GitLab accounts.
#    _gitlab_
#  commentDebounceMs:
#    # (Optional) Aggregate comments by waiting this many miliseconds before posting them to Matrix. Defaults to 5000 (5 seconds)
#    5000
```

--------------------------------

### Validate Hookshot Configuration with Docker

Source: https://matrix-org.github.io/matrix-hookshot/latest/setup

Validate the Hookshot configuration file using Docker. Mount the configuration file to the container for validation.

```bash
docker run --rm -v /absolute-path-to/config.yml:/config.yml halfshot/matrix-hookshot node config/Config.js /config.yml
```

--------------------------------

### Configure Localhost for Federated Lookups

Source: https://matrix-org.github.io/matrix-hookshot/latest/dev/setup.html

Include this configuration to ensure federated lookups work correctly when developing locally over HTTP.

```yaml
widgets:
  # ...
  openIdOverrides:
    "localhost": "http://your-synapse-listener"
```
Tokens:
Raw