Matrix Hookshot

Github, Gitlab, Jira and generic webhooks!


A Matrix bot for connecting to external services like GitHub, GitLab, JIRA, and more.


At the moment webhooks, feeds and github are supported.

bot user is admins are and

command: hookshot help gives you basic information of things


Invite to your channel, give it moderator rights and ask it to add a webhook endpoint for you

/op 50
!hookshot webhook [nameforyourwebhook]

See the endpoint url from the admin room and send a test message to it:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username": "its a me mario", "text": "yup, message from webhook", "html": "<i>yup</i><h2>formatting</h2>"}' \

To delete a webhook


Invite to your channel, give it moderator rights and ask it to add a webhook endpoint for you

/op 50
!hookshot feed [nameyourfeed]

To list existing feeds

!hookshot feed list

And to remove a feed

!hookshot feed remove


Github has a github app registered for us Matrix Hookshot to use for the integration (, github username tswfi is the owner)

Install the app into your account / organisation you want to use with hookshot.

To login to your github account talk with and check with github status if you are already logged in and with github login you can complete oauth with github.

Then in your channel you can bridge a github project to your room with !hookshot github repo If the connection is done successfully you will get a confirmation and you can start choosing what you want to get notified about.

Now that the channel is bridged to the repo you can use some commands to update issues and so on

Creating new issue

!gh create "Title text" "Description for the issue" "label1,label2"

You can omit the labels (but its best to always have some description)

Closing an issue

!gh close 3 "Yay, great job!"

Hookshot github app will also push changes to the channel. Managing what to show is defined in the room state. TODO: document how to change these:

Check all the available options in


Telegram bot entity

For Telegram side there exist bot with userhandle @HacklabFiHookshotBot that is tied into this Hookshot matrix-bot entity. Its purpose is to provide an actual user for Hookshot messages in matrix-room that is bridged to Telegram.

Bot is configured as "passive" bot, it has no reading rights inside Telegram room, it's purely echoing what hookshot says in matrix side in bridged room.

To utilize this all that is needed to do is to add the bot into the bridged Telegram room in Telegram side.

How it was installed

Running on our matrix server under user matrix-hookshot, home directory in /opt/matrix-hookshot.

Requires at least Node 16 and Rust installed. Those are installed via nvm and rustup. The base requirements for those are

sudo apt update && sudo apt upgrade
# rustup
sudo apt install curl build-essential gcc make
# node
sudo apt install build-essential libssl-dev

basic steps for creating the user, installing necessary stuff and so on (note, the curl commands are taken from and

Create user

# create user
sudo useradd --shell /usr/sbin/nologin --system --user-group --create-home --comment "Matrix Hookshot" --home-dir /opt/matrix-hookshot matrix-hookshot

Install node

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
# install nvm and rustup
curl -o- | bash
# logout and relogin to load nvm
sudo -Hu matrix-hookshot /bin/bash -l
# install node 20 (latest LTS as of writing this 20231110)
nvm install 20
# logout and relogin to load nvm with the new default node 20 config
sudo -Hu matrix-hookshot /bin/bash -l
# check that node works
node -v

the node -v command should output something like v20.9.x

install rustup

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
# start rustup installation
curl --proto '=https' --tlsv1.2 -sSf | sh
# and logout login to activate the profile
sudo -Hu matrix-hookshot /bin/bash -l
# and check that you have rust
rustc -V

The rustc -V command should output something like rustc 1.xx.xx (xxxxxx yyyy-mm-ddd)

now we can setup the bot

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
npm install -g yarn
git clone
cd matrix-hookshot

And wait while it fetches few gigs of node-modules and compiles the rust stuff


Basically copy the registration.sample.conf and configuration.sample.conf to registration.conf and configuration.conf and change all the settings.

For this instance the configuration files can be found from the server and backups in the home directory of matrix-hookshot

appservice conf (aka registration.sample.conf or registration.conf)

on our server all the appservice configurations are collected in /etc/matrix-synapse/app_service_config_files/. the file in the matrix-hookshot folder also as the service will read it too.

so always modify the registration.yml and then copy it to into /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yml

sudo cp /opt/matrix-hookshot/matrix-hookshot/registration.yml /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml
sudo chown matrix-synapse:matrix-synapse /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml
sudo chmod 600 /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml

And reload matrix-synapse after modifications.

nginx conf

add two new location blocks

        # hookshot
        location /[YOUR]/ {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/;
        location /[YOUR]/oauth {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/oauth/;
        location /[YOUR]/[PREFIX]/ {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/webhook/;
        # end hookshot

where [YOUR]/[PREFIX] is what you defined in config.yml and port is the port you defined in config.yml for webhooks

And /[YOUR]/ is something that you can choose. Values hookshot and webhook are quite obvious choices.

unit file

add unit file for this service

Description=Matrix Hookshot

ExecStart=/opt/matrix-hookshot/.nvm/nvm-exec yarn start


start everything

first validate hookshot the config in $HOME/matrix-hookshot with

yarn validate-config


  • restart synapse to get the new appservice onboard
  • restart nginx to get the proxy configuration
  • restart matrix-hookshot to restart the bridge


check secrets in the users home folder